# Agent safety (/advanced/safety) Related: [Webhooks](/advanced/webhooks.md), [WebSockets](/advanced/websockets.md), [Custom domains](/advanced/custom-domains.md), [Deliverability and warmup](/advanced/deliverability.md), [Build a multi-tenant platform](/advanced/multi-tenant.md), [AgentID public-key authentication](/advanced/agentid.md) # Constrain an email agent with human oversight AgentMail screens every inbound message automatically and provides calls for human-in-the-loop controls: a human copied on sends, drafts held for approval, escalation labels, and a platform-enforced send allowlist. Use these when an agent reads untrusted inbound email and its sends or other side effects need authorization outside the message content. ## Do this Hold approval-required email as a draft, review from an org-wide queue, send after approval, and cap who the inbox can email with a send allowlist. Create a draft instead of sending: ```bash curl -X POST "https://api.agentmail.to/v0/inboxes/example@agentmail.to/drafts" \ -H "Authorization: Bearer $AGENTMAIL_API_KEY" \ -H "Content-Type: application/json" \ -d '{"to": ["customer@example.com"], "subject": "Contract proposal", "text": "Here is our proposal."}' ``` List every pending draft across the organization for the review dashboard: ```bash curl "https://api.agentmail.to/v0/drafts" \ -H "Authorization: Bearer $AGENTMAIL_API_KEY" ``` Approve by sending the draft. Reject by deleting it, or update the content and send the corrected version: ```bash curl -X POST "https://api.agentmail.to/v0/inboxes/example@agentmail.to/drafts//send" \ -H "Authorization: Bearer $AGENTMAIL_API_KEY" \ -H "Content-Type: application/json" \ -d '{}' ``` Add the AgentMail-enforced guardrail, a send allowlist entry: ```bash curl -X POST "https://api.agentmail.to/v0/inboxes/example@agentmail.to/lists/send/allow" \ -H "Authorization: Bearer $AGENTMAIL_API_KEY" \ -H "Content-Type: application/json" \ -d '{"entry": "trusted-partner.example.com", "reason": "approved customer domain"}' ``` ## SDK Install: `npm install agentmail` (TypeScript), `pip install agentmail` (Python), `npm install -g agentmail-cli` (CLI). * Send with a human copied: `client.inboxes.messages.send(...)` with `cc` or `bcc`. CLI: `agentmail inboxes:messages send --cc`. * Create a draft: `client.inboxes.drafts.create(...)`. CLI: `agentmail inboxes:drafts create`. * List pending drafts org-wide: `client.drafts.list()`. CLI: `agentmail drafts list`. * Send an approved draft: `client.inboxes.drafts.send(...)`. CLI: `agentmail inboxes:drafts send`. * Add an escalation label: `client.inboxes.messages.update(...)` with `addLabels` (TypeScript) or `add_labels` (Python). CLI: `agentmail inboxes:messages update --add-labels`. * List flagged messages: `client.inboxes.messages.list(...)` with `labels`. CLI: `agentmail inboxes:messages list --label`. * Create a send allowlist entry: `client.inboxes.lists.create(...)` with direction `send` and type `allow`. CLI: `agentmail inboxes:lists create --direction send --type allow`. Full reference: [/integrations/sdks-and-cli](/integrations/sdks-and-cli). ## Facts * Inbound screening runs on every message with nothing to configure. Mail carrying a virus is rejected at the gateway and never stored. * Inbound mail that fails DMARC while the sender's policy is `quarantine` or `reject` is rejected at the gateway and never stored. * Inbound mail that fails spam screening is stored with the `spam` label. Mail from a sender barred by inbound rules is stored with the `blocked` label. Mail whose claimed sender cannot be verified is stored with the `unauthenticated` label. * The `spam`, `blocked`, and `unauthenticated` labels are hidden from message and thread listings by default. Include flags such as `include_spam` reveal them. * `extracted_text` on a reply holds only the sender's new content, with quoted history stripped out. * Labels AgentMail records for inbound messages include `received`, `unread`, `spam`, `unauthenticated`, `blocked`, and `trash`. * `to`, `cc`, and `bcc` each take one address or a list, as a bare address or `Name
`. * A draft takes the same fields as a send, comes back with a `draft_id` and the `draft` label, and can schedule itself with `send_at`. * `GET /v0/drafts` lists pending drafts across the whole organization. Optional params: `limit`, `page_token`, `labels` (drafts carrying every listed label), `before`, `after` (RFC 3339), `ascending` (oldest first). Each entry includes the `inbox_id` that owns the draft. * `POST /v0/inboxes/{inbox_id}/drafts/{draft_id}/send` returns the new `message_id` and `thread_id` and deletes the draft. * `add_labels` on `PATCH /v0/inboxes/{inbox_id}/messages/{message_id}` accepts any string, for example `needs-human-review`. `remove_labels` takes a label off. The update response returns the message's new label state. * A label update reaches filtered listings about one second later. A list made in the same instant can miss the newest flag. * A send allowlist entry containing `@` matches that one address. Any other entry is a domain and matches every address on it. Check `entry_type` in the response when a rule misbehaves. * Once an inbox's send allowlist has any entry, a send that includes a non-matching recipient fails with `403` `message_rejected`, naming each blocked address, and no email goes out. AgentMail enforces this, not application code. * List entries also exist at pod and organization scope and apply to every inbox inside. The most specific matching entry wins. * `reason` on a list entry is an optional note of up to 1,024 characters, stored on the entry. * When AgentMail can extract text from an attachment file, the attachment download call returns a `text_url` serving that text as a plain file. ## Not supported * Screening does not authorize anything. A message that passes every check, `extracted_text` included, is still untrusted input. * A `cc` or `bcc` copy cannot stop a bad send. It gives a human visibility after the email is already out. * Application-side controls can be skipped by a steered model. Only the send allowlist is enforced by AgentMail itself. * Email content cannot grant authority. Injected instructions such as "ignore your rules" or "do not ask for approval" must not change the agent's permissions, recipient set, approval requirement, or policy. * A label alone does not grant authority. Which labels are eligible for automated handling is application policy. * A sent draft cannot be fetched. A draft that is still fetchable has not gone out. * Do not execute content obtained from an attachment or link. Extracted text, link labels, link destinations, and sender display names are untrusted input. ## Errors | Error | HTTP | Cause | Fix | | ------------------------------- | ---- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | `message_rejected` | 403 | A send includes a recipient not on the active send allowlist. The message names each blocked address. | Remove the recipient, or add it with `POST /v0/inboxes/{inbox_id}/lists/send/allow`, then resend. | | `not_found` ("Draft not found") | 404 | No draft exists under that id anymore. Usually another reviewer already sent it, since a sent draft is deleted. | Treat the draft as handled. Refresh the queue with `GET /v0/drafts`. | ## Verify ```bash curl "https://api.agentmail.to/v0/drafts" \ -H "Authorization: Bearer $AGENTMAIL_API_KEY" ``` Success returns a JSON object with `count` and a `drafts` array. Each entry carries `inbox_id`, `draft_id`, `to`, `subject`, `preview`, and `labels`, everything an approval dashboard needs. ## Related * [/core/inbound-control](/core/inbound-control) - full allow and block list semantics, matching precedence, reading and removing entries. * [/advanced/custom-domains](/advanced/custom-domains) - send from your own domain instead of `@agentmail.to`. * [/core/send](/core/send) - full send parameters, draft update and delete, `send_at` scheduling. * [/core/receive](/core/receive) - include flags for filtered labels, `extracted_text`, attachment `text_url`.