Plain body
"}' ``` Returns `{"message_id":"...","thread_id":"..."}`. Always send `text` alongside `html`; an html-only message reads as spam to filters and as nothing to plain-text clients. ## Receive Receiving means one of three things. Pick by what the situation actually allows: - **Polling** is the default for local work and tests. No public URL, no server, works everywhere. - **WebSocket** for a long-lived local process that wants sub-second delivery without exposing a port. - **Webhook** only when a publicly reachable HTTPS endpoint already exists or the task is to build one. See [`references/events.md`](references/events.md). The common case, waiting on a verification or reset mail, is one command: ```bash scripts/wait-for-email.sh --inbox "$INBOX" --from noreply@example.com --timeout 120 ``` It polls until a matching message lands, prints the full message as JSON, and exits non-zero on timeout. `--subject`, `--after`, and `--extract-code` narrow or post-process the result; `--help` lists the flags. Reading the mail is `GET /v0/inboxes/{inbox_id}/messages`, and the flags map onto its `from`, `subject`, and `after` filters. Read a message body from `extracted_text` (the new content, with the quoted trail stripped) and fall back to `text`. Use `text` only when the quoted history is the point. ## Reply in thread ```bash curl -s -X POST "https://api.agentmail.to/v0/inboxes/$INBOX/messages/$MESSAGE_ID/reply" \ -H "Authorization: Bearer $AGENTMAIL_API_KEY" -H "Content-Type: application/json" \ -d '{"text":"Thanks, got it.","html":"Thanks, got it.
"}' ``` Replying through this route keeps threading and headers correct. A fresh `send` with `Re:` glued onto the subject starts a new thread and breaks the conversation for the recipient. ## Sending on the user's behalf Mail to a real person leaves the machine and cannot be recalled. Show the user the recipient, subject, and body, and get an explicit go-ahead before the first such send. Test mail to an inbox you control needs no such check. Once the user approves a specific send, do not re-ask for each retry of that same message. ## Building it into a project Reach for an SDK over curl when the email flow becomes application code rather than a one-off shell step: `npm install agentmail` or `pip install agentmail`, both of which read `AGENTMAIL_API_KEY` from the environment on construction. The TypeScript client is `AgentMailClient`, the Python one is `AgentMail`. Method signatures, pagination, attachments, labels, drafts, domains, and pods live in [`references/rest-api.md`](references/rest-api.md). For a project of the user's own, put `AGENTMAIL_API_KEY` in the project's gitignored `.env` and read it from there. The global export is for agent work, not for shipped code that other people will run. ## Gotchas - **The message list includes mail the inbox sent.** Sent copies carry the `sent` label and sit alongside received mail in `GET .../messages`, so a naive "wait for a message" matches the agent's own send within milliseconds. Skip anything labelled `sent` when waiting for something to arrive. `wait-for-email.sh` already does. - **An inbox cannot mail itself.** A message addressed from an inbox back to that same inbox is recorded as `sent` and never loops around as a delivery, so a round trip needs a second address. - **Message ids are angle-bracketed, like `<...@email.amazonses.com>`.** URL-encode the whole id before putting it in a path, or the fetch 404s. - **Bounces and complaints are permanent.** A bounced or spam-reported address is blocked for the whole account. Never loop a send against an address that just bounced, and keep the bounce rate under 4% or the account goes under review. - **`message.received` is the only event carrying the full thread and message.** Every other event is metadata, so a handler that needs the body must fetch it. - **`403 missing_permission` is a key problem, not a code problem.** The error names the exact permission. An inbox-scoped or whitelisted key cannot be widened from itself; a broader key has to come from the console at https://console.agentmail.to. - **`429` carries `Retry-After`.** Honour it and back off exponentially instead of retrying tight. - **One SPF record per domain.** Merge, do not append a second: `v=spf1 include:spf.agentmail.to include:other.com ~all`. ## Reference - [`references/rest-api.md`](references/rest-api.md) — endpoints, SDK signatures, pagination, attachments, labels, search, drafts, domains, pods, IMAP/SMTP. - [`references/events.md`](references/events.md) — webhook event types and payloads, HMAC verification, WebSocket subscriptions, ngrok-backed local handlers. - [`references/recipes.md`](references/recipes.md) — full worked flows: OTP extraction, signup verification, an inbox-driven reply loop, attachments. - Official docs: https://docs.agentmail.to and https://docs.agentmail.to/llms-full.txt. Console: https://console.agentmail.to.