Airmail / Developer guides
Send Email from Node.js
No Airmail-specific SDK is required. Native fetch is enough for a server-side integration.
Free Developer beta. Verified domain and manual sending approval required.
A server-side Node.js example
Use a supported Node.js release with native fetch. Set AIRMAIL_API_KEY in the process environment. Save as send.mjs, replace the example addresses, and run node send.mjs after activation. Record result.id in your own job record. Do not log request authorization headers, recipient content or raw credentials.
const response = await fetch("https://api.airmailai.tech/v1/messages", {
method: "POST",
signal: AbortSignal.timeout(15000),
headers: {
Authorization: `Bearer ${process.env.AIRMAIL_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": "account-481-welcome"
},
body: JSON.stringify({
"from": {
"email": "notifications@example.com",
"name": "Example"
},
"to": [
{
"email": "recipient@example.net"
}
],
"subject": "Welcome",
"text": "Your account is ready."
})
});
const result = await response.json();
if (!response.ok) throw new Error(result?.error?.code ?? `HTTP ${response.status}`);
console.log(result.id, result.status);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.
Test without contacting real recipients
Mock fetch in unit tests and assert the URL, JSON payload, authorization and stable idempotency header. Exercise 202, validation errors, 429 and network timeouts with fixtures. A test-labelled key is not a promise of a non-delivering sandbox. Use the dashboard controlled-validation step for the initial live proof rather than a batch of test mail.
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.