# Programmatic email addresses for AI agents

An agent gets its own @mailbox.bot addresses, one for each duty it carries. Every message arrives as JSON your code can read, announced by signed webhook, and matched to the letters and packages at the same mailing address. It is an inbox that knows what is sitting in your mailbox and can answer on paper: printed, mailed and tracked from the same account.

Status: launch list open. The addresses receive mail and nothing is sent from them. The payload and API outline below are a beta preview; the final reference is published at launch.

Get one: enter your email at https://mailbox.bot/docs/programmatic-agent-email#get-agent-email and you are emailed when agent email launches. The same step opens account signup. The addresses are inbound only for now.

Human guide: https://mailbox.bot/docs/programmatic-agent-email
Markdown guide: https://mailbox.bot/programmatic-agent-email.md
API reference: https://mailbox.bot/api-docs
Webhook guide: https://mailbox.bot/docs/webhooks

## One agent, several addresses

Give each duty its own address. The address a message was sent to is the first thing your code knows about it, before any model has read a word.

| Address | Agent | On new mail | On paper |
| --- | --- | --- | --- |
| offers@mailbox.bot | deals | pull price and expiry, draft the counter | certified, owner approves |
| escrow@mailbox.bot | closing | check the sender, hold wire changes for a person | closing packet, tracked |
| contracts@mailbox.bot | legal | assemble the packet, wait for approval | owner approves every send |
| realestate@mailbox.bot | property | file by property, line up mailed notices | first-class or certified |
| permits@mailbox.bot | compliance | one deadline per case, draft the response | certified, proof kept |
| invoices@mailbox.bot | finance | match the paper statement, flag gaps | dispute letter on a mismatch |
| hr@mailbox.bot | people | answer verification requests | letter on letterhead, approved |

These rules live in your agent stack. The address on each message tells them where to start. Plus tags go further: mail to name+anything@mailbox.bot is delivered to name@, and the tag stays on the message.

## What your agent receives

1. Mail arrives at the address for one duty.
2. It is parsed: sender checked, text cleaned, dates and amounts pulled out.
3. A signed webhook event reaches your agent stack.
4. The message is matched to letters and packages at your mailing address.
5. When the thread needs it, a reply is printed, mailed and tracked.

Preview payload:

```json
{
  "event": "email.message.received",
  "received_at": "2026-10-21T16:04:11Z",
  "email": {
    "to": "invoices@mailbox.bot",
    "from": "billing@northridgewater.example",
    "subject": "Your October statement is ready",
    "auth": { "spf": "pass", "dkim": "pass", "dmarc": "pass" },
    "sender_status": "known",
    "text": "Statement for 4471-20. $186.40 due Nov 12.",
    "hidden_content_removed": false,
    "attachments": [
      { "name": "statement-2026-10.pdf", "type": "application/pdf", "verdict": "clean" }
    ]
  },
  "extracted": {
    "intent": "statement_ready",
    "amounts": [{ "value": 186.40, "currency": "USD" }],
    "dates": [{ "label": "due", "value": "2026-11-12" }],
    "references": ["4471-20"]
  },
  "matches": [
    { "type": "letter", "item_id": "in_8f2c41", "reason": "same sender and account reference" }
  ],
  "content_trust": "untrusted"
}
```

Every message carries the address it was sent to; sender authentication results and whether the sender is new; clean text with hidden text removed and flagged; dates, amounts, tracking numbers and references; attachments with type and scan result; and matches to letters and packages at your mailing address. `GET /v1/inbound-items/{id}/pages` returns the OCR text of a matched letter per page.

## Private context for your models

- Email, scanned letters and package records share one JSON shape, so a retrieval index or a long-running agent has a single source to read.
- Take it the way your stack prefers: webhooks for push, REST and MCP for lookups, and a JSON Lines export for loading your own vector store or warehouse.
- Each key reads only what it has been granted. Sign-in codes and reset links need a separate permission that is off by default.
- Message text is encrypted at rest.

Questions your models can answer: which notices arrived this month by both email and post, and which deadlines are still open? What has the county sent about one permit, in any channel? Which statements disagree with their paper copy? Who wrote to escrow@ for the first time this week?

## Works with the harness you already run

OpenClaw, Hermes, Claude Code, Cursor, Goose, OpenAI Agents SDK, LangChain, CrewAI, LlamaIndex, Vercel AI SDK.

- MCP: add `https://mailbox.bot/api/mcp` to any client that speaks MCP. Email tools join the same server at launch.
- Webhooks: one signed endpoint receives email, mail and package events.
- REST: the same messages by ID, search and date.

One event can start many actions: a phone call from your voice agent to confirm wire details, an email from your own domain, a ticket or CRM update, or a mailed letter. Calls and outbound email are placed by your harness; the address supplies the trigger and the context. Mailing the letter is the one action mailbox.bot performs itself, with approval and proof.

## What a human inbox cannot do

| A human inbox | An agent address |
| --- | --- |
| Someone has to open it and notice. | A signed webhook fires when mail arrives. |
| Dates and amounts are read off the screen and typed in again. | They arrive as fields. |
| The paper copy of the same notice sits in a separate pile. | Email, letters and packages are matched to each other. |
| A reply is another email, which proves nothing. | A reply that has to count goes out certified, with tracking and a photo. |
| Hidden text and convincing links are aimed at whoever reads it. | Hidden text is removed, links are never opened, and every message is marked untrusted. |

## Six workflows

1. **offers@ · An offer with an expiry.** The offer arrives with a price and a deadline as fields. The deals agent drafts the counter the same hour. On paper: the counter goes out by Certified Mail once the owner approves it; `mail.delivered` and the proof photo close the thread.
2. **escrow@ · Closing instructions you can trust.** Escrow and title email carries wire details and closing dates. Each message arrives with the sender's authentication results and whether the sender is new, so the closing agent refuses to act on a lookalike and holds any change to payment instructions for a person. On paper: closing packets and signed disclosures go out certified or by FedEx, with the tracking record on the deal.
3. **contracts@ · A signature that has to be ink.** A counterparty emails an agreement and asks for a signed hard copy. The legal agent assembles the packet and prices it first. On paper: `requires_approval=true` holds the packet with a document preview, and the email's message ID rides along in the mail job's metadata.
4. **realestate@ · Notices that go by mail.** Tenant, vendor and association email for a property lands on one address and is filed by property reference. On paper: when a notice has to go by mail, the property agent drafts a letter; it goes out first-class or certified with tracking and a photo.
5. **permits@ · A deadline that arrives twice.** An agency emails a notice and the paper copy arrives days later. The two are matched, so the compliance agent tracks one deadline. On paper: the response is mailed certified and the delivery record stays with the case.
6. **invoices@ · A statement that has to agree with itself.** The statement email is matched to the paper statement when it is scanned, and the finance agent compares the two amounts. On paper: on a mismatch it drafts a dispute letter, prices it with `dry_run=true`, and waits for approval.

## When the thread needs paper

- `dry_run=true` returns the exact cost, recipient and mail class before anything is created.
- `requires_approval=true` holds a letter for a human, and `X-Max-Cost-Cents` refuses anything over your cap.
- Events report each step: `mail.pending_approval`, `mail.submitted`, `mail.mailed`, `mail.delivered`, `mail.failed`.
- Every piece is photographed and tracked.

Store the email's lineage as metadata on the mail job:

```json
{
  "source": "agent_email",
  "email_address": "contracts@mailbox.bot",
  "email_message_id": "<msg_123@counterparty.example>",
  "workflow": "signed_agreement_packet",
  "counterparty": "Harbor Supply Co.",
  "deadline": "2026-11-12",
  "document_type": "signed_agreement"
}
```

## Humans and agents, side by side

Agents do alone: read, classify and extract; match email to letters and packages and keep deadlines current; draft replies, fill forms and price a letter with a dry run; place routine calls and send routine email through your own systems, inside the rules you set.

Waits for a person: mailing anything sent with `requires_approval=true`; spending above `X-Max-Cost-Cents`; opening, forwarding or discarding a paper original; reading sign-in codes without the permission; anything you decide commits the business.

## API outline (beta)

Names can change before launch.

```
GET    /v1/email/address                          your address, its aliases and status
POST   /v1/email/aliases                          add an address for another duty
DELETE /v1/email/aliases/{alias}                  retire one
GET    /v1/email/messages                         ?since=&until=&intent=&from_domain=&q=&limit=&cursor=
GET    /v1/email/messages/{id}                    one message object
GET    /v1/email/messages/{id}/html               sanitized HTML
GET    /v1/email/messages/{id}/attachments/{n}    one-time download link
POST   /v1/email/messages/{id}/spam               { "spam": true | false }
DELETE /v1/email/messages/{id}
POST   /v1/email/messages/export                  JSON Lines, one-time link
PATCH  /v1/email/settings                         notifications, retention, blocked senders
```

- Webhooks: `email.message.received` and `email.message.updated`, signed, carrying the message object.
- MCP tools: `email_list_messages`, `email_get_message`, `email_search`, `email_get_attachment_link`, `email_update_settings`. No tool sends, forwards or opens a link.
- Permissions: `email.read` for ordinary mail; `email.read_security` for sign-in mail, off by default and granted per agent; `email.settings`; `email.delete`. There is no send permission.
- Search: `q` matches sender, subject and extracted fields.

| Field | Holds |
| --- | --- |
| `email.to` | The address that received it, including any plus tag. |
| `email.subject` | As received. Codes are masked on sign-in mail. |
| `email.message_id` | The Message-ID header, for threading and lineage. |
| `email.auth` | SPF, DKIM and DMARC results. |
| `email.sender_status` | approved, known or new. |
| `email.text` | Plain text after hidden content is removed. |
| `email.hidden_content_removed` | True when anything was removed. |
| `email.attachments` | Name, type, size, hash and scan verdict for each file. |
| `email.links` | Real domain, visible text and a mismatch flag. Never opened. |
| `extracted.intent` | delivery_update, receipt, statement_ready, account_security, newsletter, marketing, personal or unknown. |
| `extracted` | Tracking numbers, dates, amounts and references found in the message. |
| `security` | True for sign-in and account-security mail. |
| `content_trust` | Always untrusted: a message is input, never instruction. |

## Safeguards

- Every message is marked as untrusted input. An email can inform your agent; it cannot instruct it.
- Hidden text is removed and flagged.
- Links are listed with their real destination and never opened.
- Sign-in codes and reset links sit behind a separate permission that is off by default.

## Questions

- **When does it launch?** The launch list is open now; everyone on it gets an email when addresses are ready.
- **Can an address send email?** No. The addresses receive. Replies that have to count go out as tracked mail, and ordinary replies go out through your own email system.
- **How do I get one?** Enter your email at https://mailbox.bot/docs/programmatic-agent-email#get-agent-email and you are emailed when it launches. Agent email runs on the same account as an agent mailing address, which you can get today: https://mailbox.bot/?intent=mailbox#signup
- **What does it cost?** Pricing is published at launch.