Airmail / Developer guides
Transactional Email API
Application email with an acceptance boundary you can inspect. Use ordinary HTTP for onboarding updates, receipts and product notifications.
Free Developer beta. Verified domain and manual sending approval required.
Send with the REST API
Run this only after production approval. Replace the example sender with your verified domain and the recipient with an owner-controlled mailbox for your first integration check. Set AIRMAIL_API_KEY in your server environment, never in browser code. The endpoint expects structured from/to objects, not provider-specific personalizations or form fields.
curl --connect-timeout 10 --max-time 20 --fail-with-body https://api.airmailai.tech/v1/messages \
-H 'Authorization: Bearer '"$AIRMAIL_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: account-481-welcome' \
--data '{
"from": {
"email": "notifications@example.com",
"name": "Example"
},
"to": [
{
"email": "recipient@example.net"
}
],
"subject": "Welcome",
"text": "Your account is ready."
}'Acceptance and delivery are separate
A short API request persists the logical message. Provider-aware queues then pace submission independently of your application. A burst can be accepted while delivery waits for capacity. The customer dashboard separates accepted, submitted, delivered, deferred and bounced outcomes, with exact message drilldowns. This is useful when a timeout or slow destination would otherwise turn into customer support guesswork.
Handle retries without duplicates
Persist one Idempotency-Key per logical REST send. Reuse the same key and identical payload when a request times out; do not create a new key for a retry. A 202 response means durable acceptance, not final delivery. Save the msg_* ID and inspect Messages or signed webhooks for the result. After acceptance, do not resubmit deferred mail: Airmail and its delivery service own those retries. Do not automatically fail over an ambiguous send to another provider, because the first provider may already have accepted it.
Before your first production message
Start with the free Developer beta. Verify your account, create a workspace and add a domain you control: example.com and mail.example.com are both supported. Publish the records shown in Domains. Merge an existing SPF policy rather than adding another; preserve a valid existing DMARC policy. Create an API key after verification, use the dashboard for one owner-controlled validation, and request production approval. SMTP credentials become available after activation. No repository or SSH access is needed.
Know the boundaries
Airmail is a controlled public beta. Production sending requires manual approval. Paid plans remain request-access for general signups; payment never grants sending approval. Monthly allowance, daily safety quota and provider pacing are different limits. Sending is transactional by default; partnership/campaign access needs separate approval and is not a purchased-list service. Dedicated reputation isolation is not currently included. There is no inbox-placement guarantee or published OTP delivery SLA.