AgentMail API

Create an inbox, receive mail, get the OTP or the magic link. One bearer key, no IMAP, no browser.

Base URL https://$HOST · all responses JSON · overview

Authentication

Every /v1/* call except admin routes:

authorization: Bearer am_<your key>

Keys are created by an operator through POST /v1/tenants with the admin token.

Inboxes

POST /v1/inboxes

{
  "label": "github"          // optional, used for the local part
}
-> { "id": "inb_6fda88884983",
     "address": "github-12c334@myllmai.cloud",
     "label": "github",
     "account_id": 20 }

GET /v1/inboxes

-> { "count": 1, "inboxes": [ { "id": "...", "address": "...", "created_at": 1794909644831 } ] }

Messages

GET /v1/inboxes/:id/messages?limit=20

-> { "inbox": "github-12c334@myllmai.cloud", "count": 2, "source": "cloudmail",
     "messages": [ { "id":"27", "from":"noreply@github.com", "subject":"...",
                     "body":"...", "otp":"481920", "link":null, "received_at":1794910008000 } ] }

The two calls you actually need

GET /v1/inboxes/:id/otp

Latest message that contains a code. Optional ?type=link for magic links instead.

-> { "ok": true, "otp": "481920", "subject": "Your verification code is 481920",
     "from": "noreply@service.com", "received_at": 1794910008000 }
404 { "ok": false, "error": "no message yet" }

GET /v1/inboxes/:id/wait

querydefaultmeaning
typeotpotp or link
timeout25seconds, max 28
since0epoch ms — ignore older messages
# trigger the signup first, then:
curl "$BASE/v1/inboxes/$ID/wait?type=otp&timeout=25" -H "authorization: Bearer $KEY"

-> { "ok": true, "otp": "907341", "subject": "X confirmation code", "from": "info@x.com" }
408 { "ok": false, "timeout": true }

Long-poll: the connection is held until the mail lands. Returned in 7s in our test after the send.

Sending (optional)

POST /v1/send

{ "to": "user@example.com", "subject": "hi", "text": "hello", "from": "agent@myllmai.cloud" }

Requires the operator to configure a RESEND_KEY; otherwise 501.

Custom domain

POST /v1/domains

{ "domain": "mail.yourcompany.com" }
-> { "ok": true, "domain": "...", "setup": { step1..step4, mx_records: [...] } }

Add the domain as a Cloudflare zone, enable Email Routing, point it at the agentmail-api worker. Then create inboxes with {"label":"x","domain":"mail.yourcompany.com"} — any address on that domain is auto-created on first delivery.

GET /v1/domains

-> { "count": 1, "domains": [ { "domain": "...", "verified": 0 } ] }

Waitlist (public)

POST /waitlist { "email": "you@co.com", "use_case": "agent signups" }  -> { "ok": true }
GET  /waitlist   (x-admin-token)  -> { "count": 1, "waitlist": [...] }

Limits

rulevalue
inboxes per hour20 per tenant
inbox capfree 1 · dev 10 · pro 50
waitlist per IP5 / hour (IPv6 collapsed to /64)
reserved local partsadmin, postmaster, abuse, root, noreply, support, security

Python SDK

import agentmail
am = agentmail.Client("am_your_key")

inbox = am.create_inbox("github")
# ...trigger the signup with inbox["address"]...
code = am.wait_otp(inbox["id"], timeout=25)["otp"]
print(code)   # "481920"

Errors

codewhen
401missing/invalid bearer key
404inbox id not yours, or no message yet
408long-poll timed out
402plan inbox cap reached (upgrade)
429rate limited
501outbound not configured
502mailbox backend failed

AgentMail · inbox + OTP for AI agents · home · health