Airmail / Developer guides
Python Email API with Airmail
A small HTTP integration for Python applications and background jobs, without adopting a new framework.
Free Developer beta. Verified domain and manual sending approval required.
Python requests example
Install requests in your virtual environment, set AIRMAIL_API_KEY and replace the example addresses. Save this as send.py and run python send.py after sending approval. Persist the logical job and the returned message ID. Catch timeout and HTTP errors at your job boundary; retries must retain the same payload and Idempotency-Key.
import os
import requests
response = requests.post(
"https://api.airmailai.tech/v1/messages",
headers={
"Authorization": f"Bearer {os.environ['AIRMAIL_API_KEY']}",
"Idempotency-Key": "account-481-welcome",
},
json={
"from": {
"email": "notifications@example.com",
"name": "Example"
},
"to": [
{
"email": "recipient@example.net"
}
],
"subject": "Welcome",
"text": "Your account is ready."
},
timeout=15,
)
response.raise_for_status()
result = response.json()
print(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.
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.