Getting started
Create a workspace, add any sending domain you control, publish the supplied DNS records, create a server-side API key, complete one controlled validation send, and wait for production approval. A dedicated subdomain is recommended for cleaner reputation and DNS separation, but a root domain is supported.
Authentication
Use Authorization: Bearer <AIRMAIL_API_KEY> from a server only. Live keys begin with am_live_; test keys begin with am_test_. Raw keys are shown once. Creating a key does not activate unrestricted sending.
Controlled first send
Before production approval, use the customer dashboard controlled first-send step. It sends exactly one validation message from your verified domain to a mailbox you control and records the normal Airmail lifecycle: accepted, queued, submitted, and delivered. Do not use a real customer address for validation.
Send email
POST https://api.airmailai.tech/v1/messages
Authorization: Bearer am_live_example...
Content-Type: application/json
Idempotency-Key: account-481-welcome
{
"from": {"email": "notifications@example.com", "name": "Example"},
"to": [{"email": "person@example.net"}],
"subject": "Welcome",
"text": "Your account is ready."
}After production approval, a request supports one to 50 recipients, a subject, and at least one of text or html. An accepted request returns HTTP 202 and an opaque msg_* identifier. The initial status can be queued; API acceptance is not the same as final SMTP delivery.
Limited marketing transport
Marketing is an operator-approved shared-IP beta, not unrestricted bulk sending. Approved integrations set category: "marketing", send one consented recipient per request, and include the same public HTTPS unsubscribe URL visibly in the body and in one-click List-Unsubscribe headers. Airmail forces this traffic into a lower-priority queue with separate conservative limits. Transactional and OTP priority cannot be selected by the customer.
SMTP submission
Approved tenants can create an Airmail SMTP credential in SMTP settings. Connect to smtp.airmailai.tech on port 587, require STARTTLS, then authenticate with the generated username and one-time password. Airmail rejects authentication before TLS. SMTP acceptance means durable Airmail queue acceptance; it does not mean the recipient provider has delivered the message.
SMTP supports From, To, Cc, envelope Bcc, Reply-To, text, HTML and bounded standard attachments. The From domain must belong to the tenant and be fully verified. Use a stable RFC Message-ID; retrying the same DATA with the same Message-ID and content returns the same logical Airmail message.
Idempotency
Use one stable key for one logical send. Retry a timeout with the same payload and key. The same key and payload returns the same operation. A different payload with that key returns idempotency_conflict. Keys are retained for seven days.
Message status
GET https://api.airmailai.tech/v1/messages/msg_example Authorization: Bearer am_live_example...
Use GET /v1/messages/:id/events for normalized lifecycle events. Lookups are tenant scoped.
Find and diagnose a message
Open Messages in your workspace. Search a UTC date range of up to 31 days by current message status, exact recipient email, subject, submission source or recipient provider. The default view covers seven calendar days. Older results preserve the filters. A known msg_* ID opens retained message history independently of the search date range.
Message details separate acceptance, dispatch and recipient outcomes. Queue wait measures acceptance to submission; submission-to-delivery includes remote retries. SMTP transaction time, when recorded, describes an individual attempt. Missing timing, provider or TLS evidence is shown as unknown, not inferred. Provider filters cover recorded dispatch classification; legacy messages without classification do not match them.
Delivered means the recipient server accepted the message, not inbox placement or reading. Deferred messages retry automatically. Do not recreate a queued/deferred message or an uncertain submission. For mixed recipient outcomes, do not resend to recipients already delivered. Contact support with the message ID when a held, failed or uncertain message needs investigation.
The timeline shows acceptance/submission milestones and up to the latest 100 lifecycle events; truncation is labelled. Body previews and raw provider responses are not exposed. History availability follows retention policy, not the chosen search window. Message history reads have a separate per-workspace-tenant rate limit; this never consumes sending allowance.
Overview and analytics
Overview highlights setup, sending activity and your next action. Analytics adds UTC date, domain, provider and source filters. Choose 24 hours, seven days, 30 days or a custom range of up to 31 days. Charts show current recipient outcomes grouped by acceptance time, not deliveries occurring on that date. Emails sent means submitted for delivery; accepted requests can still be waiting or suppressed. Each recipient counts once, even if lifecycle notifications repeat.
Rates are hidden below 20 submitted recipients. Timing averages show their sample counts; missing measurements stay unknown. Unclassified providers remain unclassified. Monthly usage reflects accepted billing usage for the current UTC calendar month, separately from chart filters. Click a metric to inspect matching messages; one multi-recipient message may account for several outcomes. Charts may refresh up to one minute behind current data. Delivered does not guarantee inbox placement.
Domains and DNS
Airmail supplies ownership, SPF, DKIM, Return-Path and DMARC records. Root and subdomains are supported. Manual DNS setup is always available. A Cloudflare connection can optionally preview and apply non-conflicting records after explicit confirmation; credentials are workspace scoped and revocable. A domain can have only one effective SPF policy. If one already exists, Airmail shows exact merge guidance but leaves the update for manual DNS review. MX is shown only when inbound routing is enabled.
Errors
Stable codes include invalid_request, invalid_api_key, tenant_suspended, domain_not_authorized, domain_not_verified, recipient_suppressed, rate_limit_exceeded, quota_exceeded, otp_not_authorized, marketing_not_authorized, idempotency_conflict, not_found and postal_unavailable.
Limits
Configured limits appear in the customer Usage and Billing pages. Monthly plan allowance, allowed sending domains, API-key count, daily safety quota, API request rate and provider dispatch pacing are separate controls.
Security
Keep API keys in a server-side secret manager or environment. Never place them in browser JavaScript, mobile bundles, Git, logs or ordinary email.
Machine-readable contract
Download the current OpenAPI 3.1 document for API clients, request validation and integration tooling. The versioned HTTP contract remains authoritative; no third-party SDK package is required.