Airmail / Developer guides
Airmail as a SendGrid Alternative
Considering a move from SendGrid? Start with contract compatibility and operational fit, not a promise that switching providers guarantees delivery.
Free Developer beta. Verified domain and manual sending approval required.
Where Airmail fits
Airmail combines REST and authenticated SMTP with verified domains, provider-aware durable queues, Message Explorer, customer analytics, signed webhooks and suppressions. It is useful when your team wants visible acceptance and delivery stages with conservative onboarding. This is a small controlled beta, not a claim of feature parity, larger scale, lower total cost, or better inbox placement than an established platform.
Map the SendGrid contract
SendGrid uses personalizations with recipient arrays and content entries. Map each intended recipient into Airmail's to array, and content into text or html. Dynamic template IDs and SendGrid-specific categories are not interchangeable with Airmail fields.
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."
}'Cut over one application stream
Inventory your From domains, templates, attachments, scheduled jobs, suppression lists, unsubscribe rules and webhook consumers first. Verify DNS without removing the old provider records while its queue drains. Rebuild provider-specific templates and webhook verification against Airmail's contract. Carry existing opt-outs into the new sending policy before enabling traffic; contact support if you need assistance. After an owner-controlled check, move a small natural transactional stream and compare lifecycle results. Roll back new sends only; never recreate messages already accepted by either provider. Do not duplicate-send during migration.
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.
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.