# Postfleet — full documentation > Email infrastructure for AI agents. Inbound mail is parsed, classified, and > screened for prompt injection before your agent reads it; outbound send is > idempotent with optional human-in-the-loop approval. Every API endpoint lives > under the canonical /api/v1/ prefix (base URL https://api.postfleet.ai). This file inlines every docs page in full. The link index is at /llms.txt; each page is also fetchable as verbatim markdown at /docs//raw. --- Source: /docs/quickstart # Quickstart Postfleet is an email API built for autonomous agents. This page takes you from zero to a sent email, an inbound webhook, and an MCP connection. For the design decisions behind it — why an agent wants an address it owns and what has to happen to inbound mail before your model reads it — see [what an AI email agent needs from email](/ai-email-agent). Every endpoint lives under the canonical `/api/v1/` prefix and authenticates with a bearer `pf_` key. See [Authentication](/docs/auth) for the full key model. ## 1. Get an API key API keys are created and revoked in the dashboard (this is a control-plane action — it is not exposed over the data-plane API). A key is a bearer secret that starts with `pf_`. Keys carry a **scope**: - `bootstrap` — provision-only. Can create mailboxes, nothing else. - `api` / `mcp` — the working data-plane scopes: send, read, and manage drafts. Send every request with the key in the `Authorization` header: ``` Authorization: Bearer pf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ``` ## 2. Create a mailbox A mailbox is an email address your agent owns. Create one with an account-wide key (mailbox-bound keys cannot create mailboxes): ```bash curl -X POST https://your-app.example.com/api/v1/mailboxes \ -H "Authorization: Bearer pf_..." \ -H "Content-Type: application/json" \ -d '{"slug": "support"}' ``` Response (`201`): ```json { "id": "b1a2...", "address": "agent-support@your-domain.example" } ``` ## 3. Send your first email `POST /api/v1/send` takes exactly one recipient. `mailbox_id` and `text` are required; `to` is required unless you set `reply_to_message_id`, and `subject` is optional. ```bash curl -X POST https://your-app.example.com/api/v1/send \ -H "Authorization: Bearer pf_..." \ -H "Content-Type: application/json" \ -d '{ "mailbox_id": "b1a2...", "to": "person@example.com", "subject": "Hello from my agent", "text": "This email was sent by an autonomous agent." }' ``` Success (`201`): ```json { "id": "m_123...", "thread_id": "t_456...", "provider_message_id": "prov_789..." } ``` Pass an optional `client_id` to make the send idempotent — a retried request with the same `client_id` and body replays the stored result instead of sending twice. See [Sending & idempotency](/docs/sending). > If the mailbox requires human approval, `POST /api/v1/send` returns `202` > `{"draft_id": "...", "status": "pending_approval"}` instead of a message id. That is **not** > a failure and must **not** be retried — the email goes out once a human approves it. See > [Drafts & human-in-the-loop](/docs/drafts). ## 4. Receive inbound mail via webhook Configure a webhook URL and signing secret in the dashboard. When mail arrives, Postfleet POSTs a `message.received` event to your endpoint, signed with a custom HMAC: - `x-postfleet-signature` — hex `HMAC-SHA256(secret, "{timestamp}.{rawBody}")` - `x-postfleet-timestamp` — millisecond epoch, part of the signed payload Verify every event before trusting it, and reject stale timestamps (>5 minutes). Deliveries are at-least-once, so dedupe on the payload's `event_id`. The full recipe and a copy-pasteable verification snippet are in [Webhooks](/docs/webhooks). ## 5. Connect over MCP (one-liner) Point any MCP client at the Postfleet MCP server and pass your key as a bearer header: ```json { "mcpServers": { "postfleet": { "url": "https://your-app.example.com/api/mcp", "headers": { "Authorization": "Bearer pf_..." } } } } ``` This exposes tools like `send_email`, `reply_email`, `list_inbox`, `read_email`, `wait_for_email`, and the draft tools. See [MCP setup](/docs/mcp). ## Where to next - [Authentication & key scoping](/docs/auth) - [Sending & idempotency](/docs/sending) - [Drafts & human-in-the-loop](/docs/drafts) - [Send lists](/docs/lists) - [Webhooks](/docs/webhooks) - [MCP setup](/docs/mcp) --- Source: /docs/auth # Authentication & key scoping Every `/api/v1/` request authenticates with a bearer API key. Keys are opaque secrets that start with `pf_` and are stored only as a SHA-256 hash server-side. The [quickstart](/docs/quickstart) walks through issuing your first one. ``` Authorization: Bearer pf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ``` A missing or malformed header returns `401 {"error": "missing bearer token"}`; an unknown key returns `401 {"error": "invalid api key"}`. ## Key scopes Each key carries one scope. Only three scopes can authenticate a bearer request: - **`bootstrap`** — provision-only. Accepted by `POST /api/v1/mailboxes` (to create a mailbox) and nothing else. - **`api`** — the standard key for direct HTTP use. - **`mcp`** — the standard key for [the MCP server](/docs/mcp). `api` and `mcp` are interchangeable across the data-plane endpoints (send, read, drafts). A key whose scope is not permitted for an endpoint returns `403 {"error": "scope '' not permitted for this endpoint"}`. ## Mailbox-bound keys A key is either **account-wide** (`mailbox_id` is null) or **bound to a single mailbox** (`mailbox_id` set). A bound key can only ever act on its one mailbox. Each key also carries two capability flags: - **`can_read`** — may read messages and drafts (`GET` routes). - **`can_send`** — may send and create/edit/delete/send drafts (`POST`/`PATCH`/`DELETE`). Both default to true; a key is restricted only when a flag is explicitly set false. ### 403 `key_scope` When a key lacks the capability or targets a different mailbox, the response is `403` with `code: "key_scope"`: ```json { "error": "this api key cannot send", "code": "key_scope" } ``` You will see `code: "key_scope"` in these cases: | Situation | Example message | |---|---| | `can_send=false` on a send/draft-write endpoint | `this api key cannot send` | | `can_read=false` on a read endpoint | `this api key cannot read messages` | | Bound key, body `mailbox_id` is a different mailbox | `this api key is scoped to a different mailbox` | | Bound key calls an account-plane endpoint (mailboxes/domains) | `this api key is scoped to a single mailbox` | ## Data plane vs. control plane Postfleet splits its surface deliberately. **API keys operate the data plane. Sensitive control-plane operations are dashboard-only** and are never exposed to a bearer key. **Data plane (API keys):** - Send email — `POST /api/v1/send` - Read messages — `GET /api/v1/messages`, `GET /api/v1/messages/:id` - Drafts — `POST`/`GET /api/v1/drafts`, `GET`/`PATCH`/`DELETE /api/v1/drafts/:id`, `POST /api/v1/drafts/:id/send` - Provision mailboxes and custom domains — `POST /api/v1/mailboxes`, `/api/v1/domains` (**account-wide keys only** — a mailbox-bound key gets `403 key_scope` here) **Control plane (dashboard only — no API):** - Creating and revoking API keys - Managing [send allow/blocklists](/docs/lists) - Approving or rejecting [pending drafts](/docs/drafts) - Toggling a mailbox's `require_approval` setting - Configuring the webhook URL/secret and redriving dead-lettered webhook deliveries An agent holding a data-plane key therefore cannot escalate its own permissions, edit policy, approve its own drafts, or replay webhooks — those levers stay with a human. ## Anti-enumeration: cross-scope ids return 404 Resource-id endpoints never confirm that an id exists outside your scope. A message or draft id that belongs to **another account**, or (for a mailbox-bound key) to **another mailbox in your own account**, returns the same `404` as a truly missing id: ```json { "error": "message not found" } ``` ```json { "error": "draft not found" } ``` This is byte-identical to the "never existed" response, so a probe cannot tell "not yours" from "does not exist". (Body-supplied `mailbox_id` mismatches on `POST /api/v1/send` and `POST /api/v1/drafts` are the exception — those are `403 key_scope`, since a body field is a scope violation rather than an id probe.) ## Where to next - [Quickstart](/docs/quickstart) — issue a key and make the first authenticated call - [API reference](/docs/api) — every status code and error `code` this page names - [MCP setup](/docs/mcp) — where an `mcp`-scoped key goes - [Drafts & human-in-the-loop](/docs/drafts) — the control-plane approvals a key cannot reach --- Source: /docs/sending # Sending & idempotency `POST /api/v1/send` is the single outbound path for direct and [MCP](/docs/mcp) sends. It authenticates with an `api` or `mcp` key that has `can_send` — see [authentication & key scoping](/docs/auth). If you have not sent anything yet, the [quickstart](/docs/quickstart) does this end to end in about five minutes. ## Request ```bash curl -X POST https://your-app.example.com/api/v1/send \ -H "Authorization: Bearer pf_..." \ -H "Content-Type: application/json" \ -d '{ "mailbox_id": "b1a2...", "to": "person@example.com", "subject": "Subject line", "text": "Plain-text body.", "client_id": "my-unique-op-123" }' ``` | Field | Required | Notes | |---|---|---| | `mailbox_id` | yes | Must be a mailbox in your account (and, for a bound key, *your* mailbox). | | `text` | yes | Plain-text body. | | `to` | conditionally | Required unless `reply_to_message_id` is set. | | `subject` | no | Ignored on replies (derived as `Re: …`). | | `reply_to_message_id` | no | Threads the reply; derives `to` and `subject` from the original. | | `client_id` | no | 1–256 chars. Enables idempotency. Must not start with `draft:`. | | `attachments` | no | Up to 20 files. Each item is exactly one of `{content}` (standard base64) or `{url}` (HTTPS, fetched at send time). `filename` and `content_type` are optional — a URL's filename is taken from the path, otherwise `attachment`. 6 MB total inline, 30 MB total URL-backed. Use `url` for anything that would blow the request body. | Success returns `201`: ```json { "id": "m_123...", "thread_id": "t_456...", "provider_message_id": "prov_789..." } ``` ### Validation errors (`400`) - Missing `mailbox_id` or `text` → `{"error": "mailbox_id and text are required"}` - `client_id` not a 1–256-char string → `{"error": "client_id must be a string of 1-256 characters"}` - `client_id` starting with `draft:` → `{"error": "client_id must not start with \"draft:\""}` (that prefix is reserved for the internal draft-send namespace) ## Recipients **`to` is one bare address, or an array of up to 10.** There is no `cc` or `bcc`. A string that carries a second address (a comma, semicolon, or whitespace) is rejected, not split: ```json { "error": "to must be a single email address" } ``` An array longer than 10 is rejected with `to accepts at most 10 addresses`. Duplicate addresses are sent once. Each address is policy-checked, counted against quota, and screened on its own; the provider still receives one message. A `Display Name ` form is unwrapped to the bare address first. The address the policy check sees is exactly an address the provider sends to, so a smuggled second recipient cannot slip past the send-list check. If you provide neither `to` nor a reply context: `400 {"error": "to is required unless replying"}`. ## HTML `text` is always required. Optional `html` (at most 100000 characters) is sent as the HTML part alongside that text. HTML is rejected on drafts and on a mailbox that requires approval, because a reviewer would otherwise approve text the send does not show: ```json { "error": "html is not supported when the mailbox requires approval" } ``` ```json { "error": "html is not supported on drafts" } ``` ## Replying With `reply_to_message_id`, `to`/`subject`/threading are derived from the original message: - Original not found → `404 {"error": "original message not found"}` - Original in a **different mailbox**: a mailbox-bound key gets `404` (`original message not found`, anti-enumeration); an account-wide key gets `400 {"error": "original message belongs to a different mailbox"}` ## Duplicate protection (`client_id`) and the replay table Without a `client_id`, every request delivers — there is no de-duplication. With a `client_id`, the send is **idempotent per `(mailbox_id, client_id)`**. The first request claims the operation; a retried request replays the stored outcome rather than sending again. The replay decision compares a hash of the request payload (`mailbox_id` + resolved recipients + `subject` + `text` + `in_reply_to`, plus `html` and attachment digests only when those are present) against the stored operation: | Retry condition | Status | Body | |---|---|---| | Same `client_id`, same body, original already **sent** | `200` | The stored send result, replayed verbatim | | Same `client_id`, **different** body | `409` | `{"code": "idempotency_conflict", "error": "client_id was already used with a different request payload"}` | | Same `client_id`, original still **in progress** | `409` | `{"code": "idempotency_in_progress", "error": "a send with this client_id is still in progress; retry shortly"}` | | Same `client_id`, original was a **[forced draft](/docs/drafts)** | `202` | The stored `{"draft_id": "...", "status": "pending_approval"}` | | Same `client_id`, original was **rejected/failed** | stored status | The stored terminal result | Note the status split: a **first** successful send returns `201`; a **replay** of an already-sent operation returns `200`. Both carry the same `{id, thread_id, provider_message_id}`. ## Quota (`402`) When the account's monthly send quota is exhausted: ```json { "code": "monthly_send_limit", "error": "monthly send quota exhausted" } ``` with status `402`. This outcome is **terminal for that `client_id`** — retrying with the same `client_id` replays the `402`. After an upgrade, retry with a **new** `client_id`. ## Suppressed recipients (`422`) A recipient that previously bounced, complained, or unsubscribed is suppressed: ```json { "error": "recipient is suppressed (bounce/complaint/unsubscribe)" } ``` with status `422`. ## Automatic sending holds (`403`) Postfleet screens outbound activity before contacting the email provider. Sending is held across every mailbox in your account when it exceeds **20 admitted attempts in a minute** or **100 in an hour**, receives a spam complaint, or receives five distinct hard bounces within an hour. These sliding-window limits apply on every plan, separately from monthly quotas. Provider failures count toward the limits so retry loops stop too; draft creation and completed idempotent replays do not. The existing free-account distinct-recipient and daily-send limits still apply and return `429`. The existing daily bounce-rate rule also remains: three bounces, at least ten sends, and a bounce rate of 10% or more within a rolling day can hold sending before the hourly threshold is reached. ```json { "code": "sending_held", "error": "Sending is on hold. The account owner must review it in the dashboard.", "reason": "burst_limit", "hold_id": "10000000-0000-4000-8000-000000000001", "retryable": false } ``` Other reasons are `hourly_limit`, `spam_complaint`, `hard_bounces`, `owner_pause`, `bounce_rate`, `manual_review`, and `legacy_hold`. Only the signed-in owner can resume sending in **Dashboard → Mailboxes**. Switching keys or mailboxes and waiting for a window to expire do not clear a hold. Receiving mail continues. Review the agent's activity and fix its workflow before resuming; suppressed recipients remain blocked. Held mail is never delivered and does not consume monthly quota. Approved and voluntary drafts use this same gate. Resuming does not automatically send queued drafts. A hold rejection is terminal for its `client_id`: a deliberate retry after review requires a fresh ID. Existing account holds keep returning `403 account_send_held`; those release the operation claim, so you may reuse the same ID after review. They also appear in the dashboard and can be resumed there. Daily bounce history is retained after resuming, so new adverse feedback may reapply a hold. If screening is unavailable, sending fails closed with `503`, `code: "sending_safety_unavailable"`, and `retryable: true`. No email is delivered. A keyed rejection is still terminal for its `client_id`, so use a fresh ID after the service recovers. If the blocked send's quota refund needs recovery, the response is `503` with `code: "sending_cleanup_pending"`. No email was delivered. Retry **the same** `client_id` to retry cleanup, or let the scheduled cleanup sweep finish it. After cleanup, the original rejection is replayed and quota is refunded once. Known-undelivered drafts return to their original queue even while cleanup is pending; recovering an older attempt never changes a newer draft send. These controls limit damage; they cannot guarantee domain reputation or prevent a provider suspension. Already admitted sends can finish, feedback arrives after delivery, and low-volume abuse may not trigger a rate hold. This is activity and policy screening, rather than outbound content classification. ## Provider-`unknown` outcome (`502`) If the email provider call fails in a way where the send **may or may not have gone out** (a fetch-level exception), a keyed send returns: ```json { "error": "...", "retryable": false, "code": "delivery_outcome_unknown" } ``` with status `502`. On this path Postfleet **does not** finalize the operation and **does not** release quota — the send is held for server-side reconciliation so a naive retry can't duplicate a message that actually left. Same-`client_id` replays keep returning `409 idempotency_in_progress` until reconciliation resolves it. (An unkeyed send that hits an unknown outcome also returns `502` and refunds the quota, but offers no replay protection.) Ordinary transient provider errors return `502 {"error": "...", "retryable": true}`; permanent provider rejections return `400 {"error": "...", "retryable": false}`. Both are terminal for the `client_id`. ## Current limitations - **No `cc` or `bcc`.** Name every recipient in `to` (one address, or an array of up to 10). A comma inside a string is rejected. - **HTML needs a text part, and is not available on drafts or approval mailboxes.** Attachments are supported (base64 `content` or HTTPS `url`, see table above). URL-backed files are fetched at send time with the same SSRF pin as webhooks (HTTPS only, no redirects) — the URL is never forwarded to the provider. - **Terminal outcomes are sticky to the `client_id`.** A `402` quota result, a `400` permanent rejection, and a `502` transient failure all replay for the same `client_id`; a genuine retry requires a new `client_id`. - **A provider-`unknown` (`502 delivery_outcome_unknown`) operation is reconciled server-side**, not by the client. There is no API to force-resolve it; same-key replays get `409 idempotency_in_progress` until reconciliation completes. ## Where to next - [Quickstart](/docs/quickstart) — first authenticated send, start to finish - [Drafts & human-in-the-loop](/docs/drafts) — when a send should become an approval instead - [API reference](/docs/api) — the full request/response schema for this endpoint - [MCP setup](/docs/mcp) — `send_email` and `reply_email` are this endpoint, with `client_id` required --- Source: /docs/drafts # Drafts & human-in-the-loop A draft is a message prepared but not yet delivered. Drafts power two things: an agent staging work for later, and the human-in-the-loop (HITL) approval gate. ## Voluntary vs. forced drafts - **Voluntary** — you explicitly create a draft with `POST /api/v1/drafts`. It sits in status `draft` until you send it (or a human touches it). A voluntary draft is **never** forced at creation time, even on a mailbox that requires approval. - **Forced** — you call [`POST /api/v1/send`](/docs/sending) on a mailbox whose `require_approval` is on. Instead of delivering, Postfleet creates a draft in status `pending_approval` and returns `202`: ```json { "draft_id": "d_123...", "status": "pending_approval" } ``` This is **not** a failure and must **not** be retried — the email is delivered once a human approves it. Whether a mailbox requires approval is a dashboard (control-plane) setting; it is read fresh at send time, and a forced draft stays forced even if the setting is later turned off. ## Draft endpoints All draft endpoints need an `api`/`mcp` key. Reads need `can_read`; writes need `can_send` — see [authentication & key scoping](/docs/auth). The full request and response schema for each is in the [API reference](/docs/api). ### Create — `POST /api/v1/drafts` Same envelope fields as `POST /api/v1/send` (`mailbox_id` + `text` required; `to`/`subject` optional, or pass `reply_to_message_id` to draft a threaded reply; `attachments` optional). Returns `201`: ```json { "id": "d_123...", "status": "draft" } ``` ### List — `GET /api/v1/drafts?mailbox_id=…` Returns the **open** drafts (status `draft`, `pending_approval`, or `sending`), newest first: ```json { "drafts": [ { "id": "d_123...", "mailbox_id": "b1a2...", "status": "draft", "to": "person@example.com", "subject": "…", "text": "…", "reply_to_message_id": null, "requires_human": false, "thread_id": "t_…", "created_at": "…", "updated_at": "…", "attachments": [] } ] } ``` ### Get — `GET /api/v1/drafts/:id` Returns that same public draft shape. Missing, cross-account, cross-mailbox (for a bound key), and tombstoned drafts all collapse to a byte-identical `404 {"error": "draft not found"}`. ### Edit — `PATCH /api/v1/drafts/:id` Merges `to`/`subject`/`text`/`attachments` over the stored draft (an omitted field is unchanged) and re-validates through the single-recipient guard. Pass `attachments: []` to clear files. URL-backed attachments are stored as the URL and fetched when the draft is sent (not at create/update). The reply context is immutable: sending `reply_to_message_id` returns `400`. If the draft is no longer editable (it moved to `sending` or a terminal state), the guarded update loses and returns: ```json { "code": "approval_conflict", "error": "draft is no longer editable" } ``` with status `409`. ### Delete — `DELETE /api/v1/drafts/:id` `204` on success. If the draft can no longer be deleted (already `sending`/terminal), `409 {"code": "approval_conflict", "error": "draft can no longer be deleted"}`. Missing/cross-scope is `404`. ### Send — `POST /api/v1/drafts/:id/send` Voluntary send of your own draft. The mailbox's **current** `require_approval` decides the path: - Already `pending_approval` → idempotent `202 {"draft_id": "…", "status": "pending_approval"}`. - `require_approval` on → the draft is promoted into the human queue, `202` pending. - `require_approval` off → the draft is delivered through the shared send pipeline. On success, `201`: ```json { "id": "m_123...", "draft_id": "d_123...", "thread_id": "t_…", "provider_message_id": "prov_…" } ``` A lost transition (concurrent send/delete/approval) returns `409 {"code": "approval_conflict", "error": "draft can no longer be sent"}`. A rejected/failed delivery reverts the draft to `draft` and surfaces the reason; a provider-`unknown` outcome leaves the draft in `sending` (see limitations). ## `content_hash` optimistic concurrency (at approval) When a human approves a pending draft in the dashboard, they approve **the specific content they reviewed**. The approve action carries the `content_hash` (a versioned `v1:` SHA-256 over `{to, subject, text, in_reply_to}`) of the rendering they saw. If the draft was edited between render and approval, the hash no longer matches and the guarded approval loses — surfaced as `approval_conflict`. This prevents a last-second edit from being approved unseen. Note: `content_hash` is **internal** — it is not part of the public draft shape and API callers do not supply it. Editing a draft (`PATCH`) recomputes it automatically, which is what invalidates any in-flight approval. ## Tombstones — "the draft disappears after send" Once a draft is sent (or rejected, or deleted), it is **tombstoned**: it drops out of `GET /api/v1/drafts` and returns `404` from `GET /api/v1/drafts/:id`. So after a successful send, the message lives on under `/api/v1/messages` and the draft is gone. Don't treat a `404` on a previously-sent draft as an error — it's the expected end state. ## MCP draft tools - `create_draft` — stage a draft (returns `{id, status:"draft"}`). - `list_drafts` — list open drafts in a mailbox. - `send_draft` — send a staged draft by id. On a `require_approval` mailbox this returns the `202 {draft_id, status:"pending_approval"}` outcome — not a failure, do not retry; check `list_drafts`. See [MCP setup](/docs/mcp). ## Current limitations - **No `client_id` idempotency on `POST /api/v1/drafts`.** The endpoint accepts a `client_id` but does **not** de-duplicate creation on it — a retried create can produce duplicate drafts. (Idempotency applies to *sending*, not to draft *creation*.) - **No audit trail on draft create/edit/delete.** Only the approval/rejection steps are audited; `POST`/`PATCH`/`DELETE /api/v1/drafts` write no audit event. - **A provider-`unknown` draft stuck in `sending` has no redrive.** If a draft send hits an ambiguous provider outcome it stays in `sending` (reconciled server-side) and there is no dashboard or API button to force-retry it. --- Source: /docs/lists # Send lists Send lists are allow/blocklists that gate outbound recipients. Every send runs its single resolved recipient through the list policy before delivery. Lists exist at two scopes: **account** (applies to every mailbox) and **mailbox** (applies to one mailbox). Send lists are managed in the dashboard (a control-plane action); the data-plane API only **enforces** them — see [the data-plane/control-plane split](/docs/auth). ## Precedence The policy engine evaluates entries in a fixed order. With no entries at a scope, that scope imposes no restriction. 1. **Deny wins.** Block entries are checked before allow entries. An **account block** match rejects first; then a **mailbox block** match. 2. **Allow-sets intersect per scope.** If a scope has any allow entries, the recipient must match one of *that scope's* entries. The account allow-set and the mailbox allow-set are checked **independently** — matching the mailbox allow-set does **not** satisfy a non-empty account allow-set, and vice versa. 3. **The account scope is a floor.** A non-empty account allow-set constrains every mailbox; no mailbox-level entry can widen past it. So a recipient passes only if: it hits no block at either scope, **and** it satisfies the account allow-set (if any), **and** it satisfies the mailbox allow-set (if any). ## Normalization Both list patterns (at write time) and recipients (at check time) go through the **same** canonicalizer, so matching is exact equality on canonical forms: - **Case-folded.** Local part and domain are lowercased. - **IDN → punycode.** Unicode domains are converted with WHATWG `domainToASCII` (`café.com` → `xn--caf-dma.com`). - **One trailing dot stripped.** `example.com.` → `example.com`, so a trailing-dot recipient can't dodge a block. - **No plus-address stripping.** `a+tag@x.com` stays distinct from `a@x.com` — a subaddress is a different address. - Empty-label garbage (`x..com`) is rejected at both write and check time. A pattern containing `@` is an exact **address**; a bare pattern is an exact **domain** (matched against the domain after the recipient's last `@`). ## Exact-label matching — blocks do NOT cover subdomains Matching is **exact equality**. There is no wildcard, suffix, or subdomain matching. **A block on `bad.com` does NOT cover `sub.bad.com`.** To block a subdomain you must add it as its own entry. Likewise an address entry `user@bad.com` matches only that exact address, not the whole domain. ## The `403 send_blocked_by_list` response When a recipient is blocked (or fails a required allow-set), [`POST /api/v1/send`](/docs/sending) returns `403` with this structured body (there is no `error` string on list rejections): ```json { "code": "send_blocked_by_list", "reason": "block_match", "scope": "account", "list_entry_id": "le_123..." } ``` - `reason` is `block_match` (hit a blocklist entry) or `no_allow_match` (failed a required allow-set). - `scope` is `account` or `mailbox` — which scope produced the rejection. - `list_entry_id` is present **only on `block_match`** (it points at the blocking entry). A `no_allow_match` has no single entry to cite, so the field is omitted. ## Current limitations - **Exact-label only — no subdomain coverage.** A block on `bad.com` does not block `sub.bad.com`; add each subdomain (and each address) explicitly. This is the biggest gap to be aware of when relying on blocklists. - **Fail-closed rejections always report `scope: "account"`.** If a recipient can't be canonicalized at all (malformed address) and any list policy exists, the send is rejected `{"code": "send_blocked_by_list", "reason": "no_allow_match", "scope": "account"}` — the `scope` is hard-coded `account` on this fail-closed path regardless of which scope's entries exist. ## Where to next - [Sending & idempotency](/docs/sending) — the endpoint this policy gates, and the single-recipient rule it depends on - [Authentication & key scoping](/docs/auth) — why an agent's key cannot edit its own allowlist - [Quickstart](/docs/quickstart) — provision a mailbox and send through the policy --- Source: /docs/webhooks # Webhooks Postfleet delivers events to a URL you configure in the dashboard, signed with a **custom HMAC** (this is Postfleet's own scheme — it is **not** Svix). Configure the endpoint URL and a signing secret in the dashboard; both are required before any event is sent. ## Events | `type` | When | |---|---| | `message.received` | Inbound mail has been accepted and comprehended. | | `message.sent` | An outbound send was stored after the provider accepted it. | | `message.bounced` | The provider reported a bounce for an address on that send. | | `message.complained` | The provider reported a spam complaint for an address on that send. | | `attachment.scanned` | An attachment reached a terminal virus verdict (`clean` or `infected`). | `message.received` is POSTed as JSON: ```json { "event_id": "evt_9f8c...", "type": "message.received", "message_id": "m_123...", "mailbox_id": "b1a2...", "thread_id": "t_456...", "from": "sender@example.com", "subject": "Re: your message", "body": "cleaned, sanitized message body", "truncated": false, "sanitization": { "...": "trust report of what was stripped" }, "comprehension_status": "complete", "classification": { "...": "..." }, "extraction": { "...": "schema-extracted fields" }, "extraction_error": null, "confidence": 0.97 } ``` `body` is the **cleaned, sanitized** text — the pre-sanitization original is never sent. `comprehension_status` is one of `complete`, `partial`, or `skipped_injection_risk` (never `ok`); on a `partial` result `extraction`/`classification` may be null and `extraction_error` is set. [Email prompt injection: the channels, and what closes each one](/security/prompt-injection-email) walks the gates that produce these statuses and what the `sanitization` report records. Two further statuses exist on the message but are normally withheld from webhooks, because a quarantined message should not become an event your handler has to defend against: - `skipped_virus` — **never** delivered by webhook. Always readable on the message itself. - `skipped_spam` — delivered **only** if the mailbox sets `deliver_spam`. If you enable it, handle this fourth value; `extraction` is null on it. Both are always stored and readable via [`GET /api/v1/messages/{id}`](/docs/api), so nothing is lost — it is suppressed from the push surface, not discarded. `message.sent`: ```json { "event_id": "evt_9f8c...", "type": "message.sent", "message_id": "m_123...", "mailbox_id": "b1a2...", "thread_id": "t_456...", "to": ["a@example.com"], "subject": "Hello", "provider_message_id": "re_123" } ``` `message.bounced` and `message.complained` use the same fields, with `type` set to that event and `to` a single address string (the provider's recipient). `attachment.scanned`: ```json { "event_id": "evt_9f8c...", "type": "attachment.scanned", "message_id": "m_123...", "attachment_id": "att_123", "scan_status": "clean", "signature": null } ``` `scan_status` is `clean` or `infected`. A scan that errors does not emit this event. ## Deduplicate on `event_id` Delivery is **at-least-once**: a retry (or a redrive) re-POSTs the **same** payload with the **same** `event_id`. Treat `event_id` as the idempotency key and ignore an event you have already processed. ## Verifying the signature Every request carries two headers: - `x-postfleet-signature` — hex `HMAC-SHA256(secret, "{timestamp}.{rawBody}")` - `x-postfleet-timestamp` — the millisecond epoch used in the signature The signed string is the timestamp and the **raw request body** joined by a literal `.` — the timestamp is inside the MAC (Stripe-style) so a captured request can't be replayed forever. **To verify:** 1. Read the **raw** request body (exact bytes — do not re-serialize parsed JSON). 2. Recompute `HMAC-SHA256(secret, x-postfleet-timestamp + "." + rawBody)` as hex. 3. Constant-time compare it to `x-postfleet-signature`. 4. Reject if `x-postfleet-timestamp` is more than **5 minutes** old. ### Copy-pasteable verifier (Node.js) ```js const crypto = require('node:crypto'); const FIVE_MINUTES_MS = 5 * 60 * 1000; // secret: your webhook signing secret (from the dashboard) // rawBody: the raw request body STRING (not a parsed object) // signature: the x-postfleet-signature header // timestamp: the x-postfleet-timestamp header function verifyPostfleetWebhook(secret, rawBody, signature, timestamp) { // 1. Reject stale timestamps (replay protection). const ts = Number(timestamp); if (!Number.isFinite(ts) || Date.now() - ts > FIVE_MINUTES_MS) return false; // 2. Recompute the HMAC over `${timestamp}.${rawBody}`. const expected = crypto .createHmac('sha256', secret) .update(`${timestamp}.${rawBody}`) .digest('hex'); // 3. Constant-time compare. const a = Buffer.from(expected, 'hex'); const b = Buffer.from(signature, 'hex'); return a.length === b.length && crypto.timingSafeEqual(a, b); } ``` Example handler wiring: ```js app.post('/webhooks/postfleet', express.raw({ type: 'application/json' }), (req, res) => { const rawBody = req.body.toString('utf8'); const ok = verifyPostfleetWebhook( process.env.POSTFLEET_WEBHOOK_SECRET, rawBody, req.get('x-postfleet-signature'), req.get('x-postfleet-timestamp'), ); if (!ok) return res.status(401).end(); const event = JSON.parse(rawBody); // Dedupe on event.event_id, then process. res.status(200).end(); }); ``` Return any `2xx` to acknowledge. Any non-`2xx` (or a connection/timeout error) is treated as a failure and the delivery is retried. ## Retries and the retry window The first attempt fires inline when the event is enqueued; failures are retried by a cron with exponential backoff plus ±20% jitter: | Retry | Delay after previous failure | |---|---| | 1 | ~1 minute | | 2 | ~5 minutes | | 3 | ~30 minutes | | 4 | ~2 hours | | 5 | ~12 hours | That's up to **6 attempts total** (1 inline + 5 retries) over roughly **15 hours**. After the last retry fails, the delivery is **dead-lettered**. A `429` response with a sane numeric `Retry-After` (seconds, up to 24h) overrides the step for that attempt. ## Dead-letter redrive A dead-lettered delivery can be **redriven from the dashboard** (control-plane). The redrive re-POSTs the same payload with the same `event_id`, so your dedup logic still holds. There is no API endpoint for redrive — it is a dashboard-only action. ## Current limitations - **Redrive is dashboard-only** — no programmatic replay of dead-lettered deliveries. ## Where to next - [Quickstart](/docs/quickstart) — point a handler at a live mailbox and receive a real event - [Prompt injection in email](/security/prompt-injection-email) — the gates behind `comprehension_status` - [API reference](/docs/api) — reading the same message over HTTP instead of waiting for a push - [Authentication & key scoping](/docs/auth) — why redrive and secret rotation stay off the API --- Source: /docs/comprehend # Comprehend (BYO inbox) Keep AgentMail, Resend, Gmail, or any inbox you already run. When a message arrives, POST its fields to Postfleet and get a trust report back. No MX cutover, no mailbox provisioning, and no raw `.eml` in v1 — send `subject`, `text`, `html`, and optional `attachment_text`. ## What runs - **Sanitization and the heuristic injection scan** always run on what you send. - **LLM injection scan** (and content-side Haiku spam scoring) run when your account quota admits. That reservation is one **`extractions`** unit — the same meter as hosted mailbox comprehension. You do **not** need `extraction_schema_id` for the scan. Quota miss → deterministic sanitization + heuristic only (unmetered). - **Extraction** runs only when `extraction_schema_id` is supplied and that same reservation succeeded. - **Malware is not evaluated** on this path. `virus_risk` is always `null`. Attachment scanning lives on the hosted inbound route, not here. - **Spam** on the keyed route: content-side Haiku scoring runs when quota admits an LLM; SPF/DKIM/DMARC spam signals need `authentication_results` (the raw Authentication-Results header). Without quota, spam stays unevaluated unless you sent auth results. - The public [security hub paste demo](/security#demo) forces a demo schema, so content spam scoring may run there too; malware is still not evaluated. The Chrome extension calls `POST /api/v1/comprehend` with your API key (no unkeyed demo path from the extension). Full request and response shapes are in [`/openapi.json`](/openapi.json) under the `comprehend` tag. ## Example ```bash curl -sS https://api.postfleet.ai/api/v1/comprehend \ -H "Authorization: Bearer pf_..." \ -H "Content-Type: application/json" \ -d '{"subject":"Re: Invoice #1844","text":"Thanks for the update, looks good."}' ``` Use an `api` or `mcp` scoped key. Bootstrap keys are rejected. Mailbox-bound keys are allowed — you are submitting bytes, not reading a mailbox. --- Source: /docs/mcp # MCP setup Postfleet ships a Model Context Protocol (MCP) server so an agent can send and read mail as tools. It is thin-over-REST: every tool calls the same `/api/v1/` endpoints as your key, so auth, scoping, and quotas are enforced exactly once. This is a hosted email MCP server on a dedicated inbox, not a Gmail overlay — [Postfleet vs Gmail MCP Server](/compare/gmail-mcp-server). For why the agent wants its own address, see [email agent](/ai-email-agent). ## Configure the server The server speaks streamable HTTP at `/api/mcp` and authenticates with a bearer `pf_` key. Pass the key in the `Authorization` header: ```json { "mcpServers": { "postfleet": { "url": "https://api.postfleet.ai/api/mcp", "headers": { "Authorization": "Bearer pf_..." } } } } ``` The Cursor marketplace plugin in the [postfleet-mcp](https://github.com/Thestral12/postfleet-mcp) repo declares `headers.Authorization = Bearer ${POSTFLEET_API_KEY}` so the key is attached at install time. Local stdio is `npx -y @postfleet/mcp` with `POSTFLEET_API_KEY` set. A request without a `Bearer` token — including `initialize` and `tools/list` — is rejected `401`, with a `WWW-Authenticate: Bearer` header that also points at RFC 9728 protected-resource metadata: ```json { "error": "missing bearer token", "hint": "Configure this MCP server with an Authorization: Bearer pf_... header." } ``` `WWW-Authenticate` includes `resource_metadata` so a Cursor/Grok connect card can finish: it discovers `/.well-known/oauth-protected-resource` and `/.well-known/oauth-authorization-server`, then the authorize page attaches an existing `pf_` key as the access token. On hosted Postfleet every protected-resource document (and the 401 `resource_metadata` URL) advertises the same resource: `https://api.postfleet.ai/api/mcp`. Adding the hosted URL with no header will not list the server as connected. The key's scope and `can_read`/`can_send`/mailbox binding apply to tool calls exactly as they do to the REST API — see [Authentication](/docs/auth). Note that `wait_for_email` can hold a request open up to ~2 minutes, so a deployment must allow a long request duration. ## Tools Every tool is a thin wrapper over the same `/api/v1/` endpoints documented in the [API reference](/docs/api) — same validation, same error codes, same scoping. Listed in the order the server registers them, which is the order an agent scanning the roster reads top-down: discovery first, so an agent finds an existing mailbox before creating a second one. | Tool | Arguments | Purpose | |---|---|---| | `list_mailboxes` | *(none)* | List the mailboxes you can use, newest first, with id and address. Usually the first call in a workflow — every other tool needs an id reached through it. | | `create_mailbox` | `slug?`, `display_name?`, `extraction_schema_id?`, `domain_id?` | Create a mailbox this agent owns. Pass a **verified** `domain_id` from `list_domains` to host it on a custom domain instead of the shared one. | | `list_domains` | *(none)* | The account's custom sending domains with id, name, and verification status. Only `verified` domains can host mailboxes. | | `create_domain` | `name` | Register a new custom sending domain. Returns id, status, and DNS records. Paid plan required. | | `verify_domain` | `id` | Re-check DNS and refresh verification status after publishing records. | | `send_email` | `mailbox_id`, `to`, `subject`, `text`, `attachments?`, **`client_id`** | Send a **new** email. Optional `attachments` are `{filename?, content?, url?, content_type?}` — exactly one of base64 `content` or HTTPS `url`. | | `reply_email` | `mailbox_id`, `reply_to_message_id`, `text`, `attachments?`, **`client_id`** | Reply to a received message (threads automatically). | | `list_inbox` | `mailbox_id`, `limit?`, `cursor?`, `since?`, `until?`, `q?`, `thread_id?` | List messages, newest first. Pass `cursor` from the previous page. | | `read_email` | `message_id` | Read one message in full (cleaned body, sanitization report, classification, extraction). | | `wait_for_email` | `mailbox_id`, `from_contains?`, `subject_contains?`, `timeout_seconds?` | Block until a matching email arrives, or time out (`{timed_out:true}`). | | `create_draft` | `mailbox_id`, `to?`, `subject?`, `text`, `attachments?`, `reply_to_message_id?` | Stage a draft without sending. Returns `{id, status:"draft"}`. | | `list_drafts` | `mailbox_id` | List open drafts (status `draft`, `pending_approval`, `sending`). | | `get_draft` | `id` | Read one draft in full: recipient, subject, body text, and current status. | | `update_draft` | `id`, `to?`, `subject?`, `text?`, `attachments?` | Edit an unsent draft; omitted fields keep their current value. Pass `attachments` to replace files, or `[]` to clear them. The reply target can't be changed, and a draft already sending or sent can't be edited. | | `send_draft` | `id` | Send a staged draft by id. | | `delete_draft` | `id` | Discard a draft so it will never be sent. Already-sending or sent drafts can't be deleted. | `client_id` is **required** on `send_email` and `reply_email` — unlike the REST API, where it stays optional for compatibility with direct callers. Pass any unique string you make up, and reuse the **same** one if you retry after an error: that is what makes the send at-most-once. [Sending & idempotency](/docs/sending) has the full replay table for what a repeated `client_id` returns in each state. An optional guard is precisely the one an agent omits, so the MCP schema requires it. The `draft:` prefix is reserved for the approval flow's own keys and is rejected. `read_email` never returns the pre-sanitization raw body — only the cleaned, screened content reaches the agent. ## The 202 pending-approval outcome If a mailbox requires human approval, `send_email`, `reply_email`, and `send_draft` do **not** send immediately. They return the queued-draft shape instead of a message id: ```json { "draft_id": "d_123...", "status": "pending_approval" } ``` **This is a success, not an error, and it must not be retried.** The email is delivered once a human approves the draft in the dashboard. To follow up, call `list_drafts` — a `pending_approval` entry is still waiting on a human; once approved it is sent and tombstoned (drops off the list). Distinguish the two success shapes: - `{ "id": "...", "thread_id": "..." }` → sent. - `{ "draft_id": "...", "status": "pending_approval" }` → queued for human approval. See [Drafts & human-in-the-loop](/docs/drafts) for the full approval model. ## Errors Tool errors come back as a short message plus a recovery hint (never a stack trace), for example an invalid key (`401`), a scope/capability rejection (`403`), quota exhaustion (`402`), a not-found id (`404`), a domain already registered (`409`), a suppressed recipient (`422`), the email-provider domain cap (`403` `provider_domain_limit` — not the Postfleet $20 plan; do not retry until an operator raises provider capacity), a provider rejection (`502` — permanent for `verify_domain` and most `create_domain` failures; send tools may retry with the same `client_id`), or a missing provider configuration (`503`). A `503` means the hosted API has no provider key; retrying or using the dashboard will not help until an operator configures it. The underlying status and shapes match the REST API documented throughout these pages. --- Source: /docs/sdk # TypeScript SDK The `postfleet` package is a typed client for the `/api/v1` REST API. Responses come back verbatim — no stripping, no synthetic wrappers. Node 18+ (global `fetch`). ## Install ```bash npm install postfleet ``` A `pf_` API key from https://postfleet.ai. Override the origin with `baseUrl` for staging or self-hosted. ```ts import { Postfleet } from 'postfleet'; const pf = new Postfleet({ apiKey: process.env.POSTFLEET_API_KEY! }); ``` ## Quickstart Create a mailbox, wait for a reply, then send in-thread: ```ts const box = await pf.mailboxes.create({ display_name: 'Support agent' }); const incoming = await pf.messages.waitFor({ mailbox_id: box.id }); if (!incoming) throw new Error('timed out waiting for mail'); // Read body_clean: the sanitized text. body_raw is the pre-sanitization original, // kept for audit — the exact surface the screening pipeline stripped. console.log(incoming.body_clean); await pf.messages.send({ mailbox_id: box.id, reply_to_message_id: incoming.id, text: 'Got it — working on this now.', client_id: 'reply-1', }); ``` ## Resources | Method | Endpoint | |---|---| | `pf.mailboxes.create` | `POST /api/v1/mailboxes` | | `pf.mailboxes.list` | `GET /api/v1/mailboxes` | | `pf.domains.list` | `GET /api/v1/domains` | | `pf.domains.create` | `POST /api/v1/domains` | | `pf.domains.verify` | `POST /api/v1/domains/{id}/verify` | | `pf.messages.list` | `GET /api/v1/messages?mailbox_id&limit&cursor&since&until&q&thread_id` | | `pf.messages.get` | `GET /api/v1/messages/{id}` | | `pf.messages.send` | `POST /api/v1/send` | | `pf.messages.waitFor` | polls `GET /api/v1/messages` then `GET /api/v1/messages/{id}` | | `pf.drafts.create` | `POST /api/v1/drafts` | | `pf.drafts.list` | `GET /api/v1/drafts?mailbox_id` | | `pf.drafts.get` | `GET /api/v1/drafts/{id}` | | `pf.drafts.update` | `PATCH /api/v1/drafts/{id}` | | `pf.drafts.delete` | `DELETE /api/v1/drafts/{id}` | | `pf.drafts.send` | `POST /api/v1/drafts/{id}/send` | | `pf.comprehend.run` | `POST /api/v1/comprehend` | `messages.send` and `drafts.send` return the sent shape on `200`/`201`, or `{ draft_id, status: "pending_approval" }` on `202` when the mailbox requires a human. That is a success — do not retry. See [Drafts & human-in-the-loop](/docs/drafts). Screen email you already have (no mailbox required): ```ts const report = await pf.comprehend.run({ subject: 'Re: invoice', text: 'Please wire $5000 to …', }); console.log(report.status, report.heuristic_risk, report.not_evaluated); ``` See [Comprehend (BYO inbox)](/docs/comprehend) for quotas, when the LLM scan runs, optional `extraction_schema_id`, and what is not evaluated on this surface. ## `waitFor` `pf.messages.waitFor({ mailbox_id, from_contains?, subject_contains?, timeout_ms?, poll_interval_ms? })` polls the inbox until a matching **inbound** message arrives whose `created_at` is at or after the call started. Optional `from_contains` / `subject_contains` are case-insensitive substrings. Defaults: timeout 60 000 ms, poll every 2 000 ms. Returns the full message on a hit, or `null` on timeout. ## Errors Non-2xx responses and network failures throw `PostfleetError`: - `status` — HTTP status, or `0` when `fetch` itself throws - `code` — API `code` when present (`key_scope`, `delivery_outcome_unknown`, …) - `retryable` — API `retryable` when present; `true` on network failure - `body` — parsed JSON, or `{}` if the body was not JSON ```ts import { PostfleetError } from 'postfleet'; try { await pf.messages.send({ mailbox_id, to, subject, text, client_id }); } catch (err) { if (err instanceof PostfleetError && err.retryable) { // retry with the SAME client_id } throw err; } ``` ## Idempotency `client_id` stays optional and the SDK never mints one. Generate a `client_id` once per logical send and reuse it on retry; never mint a new one per attempt. A fresh key per attempt is exactly the double-send the key prevents. See [Sending & idempotency](/docs/sending). ## Not in v0.1 No retries with backoff, and no Python SDK. Both are later, separate decisions. The full request and response shapes live in the [API reference](/docs/api). --- Source: /docs/api # API reference Every Postfleet endpoint lives under `/api/v1/` and authenticates with a bearer `pf_` API key: ``` Authorization: Bearer pf_... ``` A machine-readable OpenAPI 3.1 description of this surface is served at [`/openapi.json`](/openapi.json). It documents shipped behavior only — every path, method, status code, request field, and error `code` is transcribed from the route handlers and kept honest by a drift test. Point your OpenAPI client, code generator, or agent at that file. The narrative guides — [sending & idempotency](/docs/sending), [drafts & HITL](/docs/drafts), [send lists](/docs/lists), [authentication](/docs/auth), [webhooks](/docs/webhooks), and [comprehend (BYO inbox)](/docs/comprehend) — explain the semantics behind these endpoints. The [quickstart](/docs/quickstart) calls the first few of them in order; [MCP setup](/docs/mcp) exposes the same surface as agent tools. ## Endpoints ### Send - `POST /api/v1/send` — send an email. Optional `client_id` for idempotent duplicate protection. Optional `attachments` (base64 `content` or HTTPS `url`). On a `require_approval` mailbox the send is queued as a forced draft (`202`). ### Messages - `GET /api/v1/messages?mailbox_id=` — list messages in a mailbox. Optional `limit` (clamped at 100), `cursor`, `since`, `until`, `q`, and `thread_id`. The body includes `next_cursor` (null on the last page). (`can_read`). - `GET /api/v1/messages/{id}` — get one message with body, comprehension, and attachments (`can_read`). ### Comprehend - `POST /api/v1/comprehend` — screen email you already have (BYO inbound). No mailbox required. Malware is not evaluated; spam signals need `authentication_results` when you have them. Paid LLM injection scan runs when `extractions` quota admits — no `extraction_schema_id` required. Supply a schema only if you also want extract. Quota miss is deterministic sanitization + heuristic (unmetered). See [Comprehend (BYO inbox)](/docs/comprehend). ### Drafts - `POST /api/v1/drafts` — create a voluntary draft (`can_send`). - `GET /api/v1/drafts?mailbox_id=` — list open drafts in a mailbox (`can_read`). - `GET /api/v1/drafts/{id}` — get a draft (`can_read`). - `PATCH /api/v1/drafts/{id}` — edit a draft's envelope (`can_send`). - `DELETE /api/v1/drafts/{id}` — discard a draft (`can_send`). - `POST /api/v1/drafts/{id}/send` — send a draft. Delivers (`201`) or, on a `require_approval` mailbox, promotes to the human queue (`202`). ### Mailboxes - `POST /api/v1/mailboxes` — provision a mailbox. Account-plane: rejected for a mailbox-bound key. ### Domains - `POST /api/v1/domains` — add a custom sending domain (paid plan). - `GET /api/v1/domains` — list custom domains. - `POST /api/v1/domains/{id}/verify` — re-check a domain's verification. ## Error shapes Errors are JSON. Client-facing failures with a stable machine-readable `code`: - `403` `key_scope` — the key cannot perform this action, or is scoped to a different mailbox, or is a mailbox-bound key on an account-plane route. - `403` `send_blocked_by_list` — the recipient is blocked by a send list; carries `reason` (`block_match` / `no_allow_match`), `scope` (`account` / `mailbox`), and `list_entry_id` on a block match. - `409` `idempotency_conflict` — the `client_id` was reused with a different payload. - `409` `idempotency_in_progress` — a send with this `client_id` is still running; retry shortly. - `409` `approval_conflict` — the draft is no longer editable / deletable / sendable (a concurrent transition moved it). - `502` `delivery_outcome_unknown` — an ambiguous provider outcome; the send may or may not have gone out and is left for reconciliation. Other statuses: `400` validation, `401` bad bearer, `402` quota exhausted, `404` not found (also returned for cross-account and cross-mailbox ids as anti-enumeration), `422` suppressed recipient. Cross-account and cross-mailbox object ids return `404` rather than `403` so a caller cannot enumerate ids it does not own.