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
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.
{
"label": "github" // optional, used for the local part
}
-> { "id": "inb_6fda88884983",
"address": "github-12c334@myllmai.cloud",
"label": "github",
"account_id": 20 }
-> { "count": 1, "inboxes": [ { "id": "...", "address": "...", "created_at": 1794909644831 } ] }
-> { "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 } ] }
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" }
| query | default | meaning |
|---|---|---|
type | otp | otp or link |
timeout | 25 | seconds, max 28 |
since | 0 | epoch 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.
{ "to": "user@example.com", "subject": "hi", "text": "hello", "from": "agent@myllmai.cloud" }
Requires the operator to configure a RESEND_KEY; otherwise 501.
{ "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.
-> { "count": 1, "domains": [ { "domain": "...", "verified": 0 } ] }
POST /waitlist { "email": "you@co.com", "use_case": "agent signups" } -> { "ok": true }
GET /waitlist (x-admin-token) -> { "count": 1, "waitlist": [...] }
| rule | value |
|---|---|
| inboxes per hour | 20 per tenant |
| inbox cap | free 1 · dev 10 · pro 50 |
| waitlist per IP | 5 / hour (IPv6 collapsed to /64) |
| reserved local parts | admin, postmaster, abuse, root, noreply, support, security |
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"
| code | when |
|---|---|
| 401 | missing/invalid bearer key |
| 404 | inbox id not yours, or no message yet |
| 408 | long-poll timed out |
| 402 | plan inbox cap reached (upgrade) |
| 429 | rate limited |
| 501 | outbound not configured |
| 502 | mailbox backend failed |