---
title: Inboxes
description: Email addresses that keep mail in threads and reply from the same address, for an AI agent or for people.
---

An inbox is one email address that receives mail into threads and sends from the same address. Give one to an AI agent, which reads it through the API, webhooks or the [MCP server](/docs/mcp), or to people, who read it in the dashboard. An inbox is an address on one of your [receiving domains](/docs/receiving), or an address on BillionSend's shared domain that needs no DNS.

The [SDKs](/docs/sdks) cover every inbox endpoint as `inboxes.*`, including the safety rules, quarantine, approvals and the live event stream.

> **Info**
>
> Inboxes are in beta, under **Inboxes** in the dashboard.

## Agent or people

Every inbox has a `kind`, chosen when it is created and never changed. The kind sets the defaults of the safety settings.

| Setting | Agent | People |
| --- | --- | --- |
| `accept_from` | `verified` | `anyone` |
| `screening` | on | off |
| `extract_codes` | on | on |
| `send_policy` | `reply_only` | `open` (`reply_only` on the shared domain) |
| `require_approval` | off | off |
| `private_codes` | on | off |
| `send_cap` | 200 (50 on the shared domain) | none (50 on the shared domain) |

- **`agent`** is the default when `kind` is left out. Mail from senders whose domain does not vouch for them waits in quarantine, mail from other outside senders is screened for prompt injection, and the agent replies inside existing threads: a new conversation it starts becomes a draft that waits for a person. See [Agent safety](/docs/agent-safety).
- **`human`** is for people reading in the dashboard: everyone's mail is delivered (a failed authentication lands in the `spam` folder) and nothing is screened.

Mail carrying a virus is quarantined in every inbox.

## Create an inbox

In the dashboard, open **Inboxes** and choose **Create inbox**. Or call the API:

```sh
curl -X POST "https://api.billionsend.com/inboxes" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email_address": "orders@inbound.example.com",
    "name": "Orders agent",
    "kind": "agent"
  }'
```

With the Node.js SDK:

```ts
import { BillionSend } from "@billionsend/node";

const bs = new BillionSend(); // reads BILLIONSEND_API_KEY

const { data, error } = await bs.inboxes.create({
  email_address: "orders@inbound.example.com",
  name: "Orders agent",
  kind: "agent",
});
```

The answer (`201`) is the whole inbox: `id`, `name`, `email_address`, `domain_id`, `kind`, `shared`, `expires_at`, `unread` (threads with an unread message), `drafts`, `quarantined`, `pending_approval` and more.

| Field | Rules |
| --- | --- |
| `email_address` | An address on a verified domain of your team that receives mail. Lowercased; the part before `@` takes up to 64 letters, digits and `. _ % + -`. It cannot change later. Leave it out for an address on the shared domain. |
| `username` | With `email_address` left out, the part before `@` on the shared domain; left out, the address is random. With a `domain_id` of one of your own domains, it is the part before `@` there. |
| `domain_id` | A `GET /domains` row: your team's shared subdomain (`shared: true`), or one of your verified domains. |
| `name` | 1 to 320 characters; the address when left out. |
| `from_name` | Display name of the mail the inbox sends, up to 78 characters: a plain name, without `@`, `:`, `<`, `>`, line breaks, links or phone numbers. |
| `kind` | `agent` (default) or `human`. |
| `expires_in` | When the inbox expires, such as `1h`, `24h` or `7d`; left out, never. |
| `safety` | Any of the safety settings. |
| `forwarding` | `true` adds a `receiving_address` on the shared domain, to forward a mailbox you keep elsewhere into the inbox. |

| Answer | When |
| --- | --- |
| `409 validation_error` | Another inbox already uses the address. No other name is picked for you. |
| `403 validation_error` | Your plan's inbox limit is reached. |
| `429 rate_limit_exceeded` | Too many inboxes created in the last hour, or the shared domain's name review reached today's limit. `retry-after` says when to retry. |
| `422 validation_error` | The domain is not verified or does not receive mail, a `username` breaks a rule or is reserved, or a setting breaks a rule. |
| `503 name_review_unavailable` | A shared-domain name could not be reviewed right now. Try again shortly. |

The other calls:

- `GET /inboxes` lists inboxes, newest first (`?kind=agent` or `?kind=human` narrows it).
- `GET /inboxes/{id}` reads one. Every `{id}` in an `/inboxes/{id}/…` path takes the inbox's id or its email address.
- `PATCH /inboxes/{id}` changes `name`, `from_name` or `expires_in`.
- `DELETE /inboxes/{id}` deletes the inbox with its threads, drafts and labels, and revokes its API keys. A message that also reached another inbox or a catch-all address stays there.

## Addresses

### Your own domain

An inbox on your own domain needs the domain to [receive mail](/docs/receiving): verified, with receiving on and its MX record published. Each message goes by the address the sender's server delivered to:

1. to the inbox with exactly that address;
2. otherwise, for `name+tag@`, to the inbox of `name@`;
3. otherwise, when the domain's catch-all is on, to **All received** without an inbox; with catch-all off, the address is refused (`550 5.1.1`).

Mail sent from an inbox's address follows the inbox's rules on every surface: `POST /emails`, the batch endpoint, the SMTP relay and MCP. Give an inbox an address your app does not already send from.

### Shared domain

A shared-domain inbox needs no DNS. Each team gets its own subdomain on BillionSend's shared domain, named after the team. Leave `email_address` out, or send the shared row's id as `domain_id`, and `username` names the address:

```sh
curl -X POST "https://api.billionsend.com/inboxes" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{ "username": "orders", "name": "Orders agent" }'
```

Without `username` the address is random. A username is refused (`422`) when it is reserved (postmaster, abuse, admin, security, support, noreply, no-reply, billing, hostmaster, webmaster, mailer-daemon, root), starts with `fwd-`, or looks like a well-known brand. One that is taken answers `409`.

**Name review.** A chosen username, a `from_name` and the team's subdomain are reviewed before they are published, to stop names that pose as a brand, a bank, a government or an official role. A refused name answers `422`. While the review cannot answer you get `503 name_review_unavailable`; a new team's subdomain is retried until it passes, and after 24 hours the team takes `team-` and six random characters. Past 20 refused names or 200 reviews in a UTC day, the answer is `429` until midnight UTC.

Shared addresses follow rules of their own, since the domain is every team's:

- They last until deleted, unless `expires_in` says otherwise, and count toward your plan's inbox limit. One nobody used for 90 days is deleted.
- On the **Free** plan, and for any address whose name looks like a well-known brand, they only reply inside their own threads, to senders whose domain vouched for them and to your team members' sign-in addresses. On a paid plan, people start conversations from them, and an agent does when its `send_policy` is `open` and your team is past its first sends; otherwise its new conversations wait for a person as drafts. Each message to a stranger is checked for phishing before it goes out. A refusal answers `403 inbox_send_policy`.
- Each email goes to 10 recipients at most. An inbox sends to 50 recipients a day at most (`send_cap` from 1 to 50), and all your team's shared addresses together reach 1,000 recipients per UTC day; past it, `429 inbox_send_cap_reached`.
- `from` must be the inbox's address exactly, and the email cannot carry `scheduled_at`, `reply_to`, attachments or custom headers (`422`). `POST /emails/batch`, broadcasts and the SMTP relay always refuse a shared address.
- `forward_to` takes members' sign-in addresses only.

Mail to `postmaster@` and `abuse@` on the shared domain goes to BillionSend, never to an inbox.

### Forward a mailbox into an inbox

`forwarding: true` is for an address whose mail lives elsewhere, such as a Google Workspace mailbox. The inbox gets a `receiving_address`, a random address on your team's shared subdomain: forward the mailbox there, and the inbox receives the mail while replying from its own address. The domain then only needs to be verified for sending.

## Expiry

`expires_in` is a number followed by `h` or `d`, from `1h` to `365d`; left out, the inbox never expires. A `PATCH` with a new `expires_in` counts from that moment, and `null` removes the expiry. `expires_at` shows when it ends.

At `expires_at` the inbox stops: mail to it is refused (`550 5.1.1`), reads answer `404` and its API keys stop working. Within the hour it is deleted, with an `inbox.expired` webhook followed by `inbox.deleted`. Changing the expiry takes the developer, admin or owner role.

## Threads

Every message of an inbox belongs to a thread, and a thread holds both directions: what the inbox received and what it sent.

- **How replies find their thread.** Mail the inbox sends carries a thread token in its `References` header. A reply lands in the same thread when it carries that token, when its `In-Reply-To` names a message the inbox sent, or when it refers to an earlier message of the thread. Subjects never join threads.
- **Folders.** A thread sits in one folder: `inbox`, `archive`, `spam`, `sent` or `trash`. New mail moves an archived or sent thread back to `inbox`. `DELETE` moves a thread to `trash`, which is emptied after 30 days.
- **Read state.** A `PATCH` with `read` marks the whole thread. Held mail never makes a thread unread. In a people inbox, opening a thread marks it read; in an agent inbox, read state belongs to your agent.
- **Labels.** Up to 100 per inbox, names of 1 to 64 characters, colors as `#RRGGBB`.

| Call | Does |
| --- | --- |
| `GET /inboxes/{id}/threads` | Threads, latest activity first. Filters: `folders`, `labels`, `read`, `include_quarantined`. |
| `GET /inboxes/{id}/threads/search` | The same filters plus `query` (`"exact phrase"` and `-excluded` work), `from`, `to`, `cc`, `bcc`, `has_attachment`, `start_date`, `end_date`. |
| `GET /inboxes/{id}/threads/{thread_id}` | One thread. |
| `PATCH /inboxes/{id}/threads/{thread_id}` | Set `read` or `folder`. |
| `POST` / `PUT` / `DELETE …/threads/{thread_id}/labels` | Add, replace or remove labels. |
| `DELETE /inboxes/{id}/threads/{thread_id}` | Moves the thread to trash. |
| `GET /inboxes/{id}/threads/{thread_id}/emails` | Its emails, oldest first. |

Search matches whole words, in any letter case, in the subject, the sender (address and display name), the recipients, the text of a received email (the earlier messages it quotes included), its attachment names and the text of its PDF, Word and Excel attachments (once that text has been read). Chinese, Japanese and Korean text is split into words. Every word of `query` must match somewhere in the same email; `from`, `to`, `cc` and `bcc` take words of an address or a name. Sent emails are searched by subject, sender and recipients.

`matched_email_id` is the thread's best match, and `highlights` marks the words in its subject, sender and recipients (it is `{}` when only the text or an attachment name matched). A new email is searchable a second or two after it arrives. If search is briefly unavailable, the call answers `503` with `search_unavailable` and a `Retry-After` header; every other call works as usual.

A thread email has `direction`, `from`, `to`, `cc`, `bcc`, `reply_to`, `subject`, `message_id`, `html`, `text`, `attachments`, `read` and `received_at`. Received mail adds `extracted_text` (the reply, cleaned of hidden text), `screening`, `spam_verdict` and `virus_verdict`.

## Send from an inbox

`POST /inboxes/{id}/emails` (`inboxes.send()` in the SDKs) starts a new conversation from the inbox address in one call.

```sh
curl -X POST "https://api.billionsend.com/inboxes/{id}/emails" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-confirmation" \
  -d '{
    "to": "ada@example.org",
    "subject": "Your order 1042",
    "text": "It ships today. The invoice is attached.",
    "attachments": [{ "filename": "invoice.pdf", "content": "JVBERi0xLjQK..." }]
  }'
```

It takes `to`, `subject`, `html` and/or `text`, and optionally `cc`, `bcc`, `attachments` and `requires_approval`. The inbox's rules decide as they do for a reply, and the answers are a reply's: `200` with `{ "id", "thread_id" }`, or `202` with the draft when the rules hold the send (an inbox that may not start conversations, a first-time recipient past the ramp, `requires_approval: true`). An inbox-scoped key can call it for its own inbox.

**Attachments** are the ones `POST /emails` takes: `filename` and base64 `content`, optionally `content_type` and `content_id` for an inline image. A remote `path` answers `422`. Replies, forwards, new sends and drafts all take them, up to 10 MiB decoded in all (a forward counts the original's files too); programs and disguised file types answer `422`, and an inbox on the shared domain takes none.

## Reply and forward

```sh
curl -X POST "https://api.billionsend.com/inboxes/{id}/threads/{thread_id}/emails/{email_id}/reply" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-reply" \
  -d '{ "text": "Thanks, your order ships today." }'
```

A reply goes to the message's `Reply-To`, or else its sender. `reply_all` adds the other `to` and `cc` addresses as `cc`; `bcc` is never copied. One send takes 50 recipients at most. `…/forward` needs `to`, takes a note, and quotes the original with its attachments, plus any `attachments` you add (up to 10 MiB in all). Both take `attachments` and `requires_approval: true` to have a person approve the send. A reply from an agent inbox carries `Auto-Submitted: auto-replied`.

| Answer | Means |
| --- | --- |
| `200` | Sent: `{ "id", "thread_id" }`. |
| `202` | Held for a person: the draft, with `status: "pending_approval"` and its `approval_reasons`. |
| `403 inbox_send_policy` | The inbox's rules refuse the send outright. |
| `403 email_quarantined` | The email is held in quarantine, or carries a virus. |
| `403 restricted_api_key` | An inbox-scoped key reaching another inbox. |
| `429 inbox_send_cap_reached` | The inbox's daily cap is used; `retry-after` counts to midnight UTC. |

To reply to any received email, in an inbox or not, use [`POST /emails/receiving/{id}/reply`](/docs/receiving).

## Drafts and approval

A draft is standalone for a new conversation, or a reply with `thread_id` and `reply_to_email_id`. Its `status`:

| `status` | Means |
| --- | --- |
| `draft` | Being written; nothing sends it until `…/send`, or until its `send_at`. |
| `pending_approval` | A send was held and waits for a person. `approval_reasons` says why. It expires after 7 days. |
| `sent` | Sent; `email_id` names the email. |
| `rejected` | A person turned it down. |
| `expired` | Nobody approved it within 7 days. |

| Call | Does |
| --- | --- |
| `POST /inboxes/{id}/drafts` | Creates a draft: `to`, `cc`, `bcc`, `subject`, `text`, `html`, `attachments`, plus `thread_id` and `reply_to_email_id` for a reply. A reply draft does not copy recipients, so set `to` before sending. |
| `GET /inboxes/{id}/drafts` | Unsent drafts, most recently updated first. |
| `GET` / `PATCH` / `DELETE /inboxes/{id}/drafts/{draft_id}` | Read, change (setting `text` or `html` replaces the whole body, and `attachments` replaces the whole list) or delete a draft; `409` once sent. |
| `POST /inboxes/{id}/drafts/{draft_id}/send` | Sends it. `200` with the sent email's `id` and `thread_id`, `202` when held, `422` without a recipient. |
| `POST /inboxes/{id}/drafts/{draft_id}/reject` | Turns a draft down (approvers only). |

A draft keeps its `attachments` encrypted, apart from its body, and reads them back by position as `id`, `filename`, `content_type` and `size`, never the content. They go out with the email when the draft is sent, and a held send keeps the files it carried with its draft. Once a draft is sent, rejected, expired or deleted its files are gone, and the 30-day content purge removes any that are left.

**Scheduled sends.** `send_at` on `POST` or `PATCH` (a BillionSend extension) sends the draft later, as whoever set it (an edit of a scheduled draft's content makes the editor the one it sends as): an ISO 8601 time with offset, or a relative one like `"in 2 hours"`, at most 30 days ahead; a time already past sends it within a minute, and `null` cancels. The draft needs a recipient by then, and only a `draft` can be scheduled: one waiting for approval answers `409`. When `send_at` comes, the send runs every rule and limit as a send made then would. Sent, the draft turns `sent`; held by the inbox's rules, `pending_approval`; refused (the key that scheduled it was revoked, the inbox is gone, a limit was reached), it stays a `draft` with `send_at` back to `null`, the refusal's name in `send_error` and an `inbox.draft.send_failed` webhook that carries `error: { name, message }`. Scheduling it again clears `send_error`. With `send_at`, creating a second reply draft for the same email answers `409` instead of the existing draft.

**Who approves.** A person in the dashboard, or a full-access API key of the team that is not restricted to an inbox, approves by sending: the send skips the rules that hold agent mail. An agent cannot approve: an inbox-scoped key or an MCP client sending a pending draft gets `403 approval_required`. In the dashboard, any member approves, edits or discards drafts under the inbox's **Needs review** tab, and owners get one email a day while something waits.

Reasons a send is held:

| Reason | Held because |
| --- | --- |
| `approval_required` | The request asked for a person (`requires_approval: true`). |
| `require_approval` | The inbox has every send approved. |
| `send_policy` | A recipient is not allowed by the inbox's send policy. |
| `ramp` | Too many new recipients today for a young inbox. |
| `private_code` | It contains a code or sign-in link the inbox received. |
| `loop_guard:<reason>` | It replies to an automatic message (out-of-office, mailing list, bounce). |
| `loop_burst` | Too many automatic replies to one address within an hour. |
| `reply_to_redirect` | The message's Reply-To points to another organization. |

## Safety settings

`GET /inboxes/{id}/safety` reads an inbox's rules, and `PATCH` changes any of them:

```sh
curl -X PATCH "https://api.billionsend.com/inboxes/{id}/safety" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "accept_from": "allowlist",
    "allowlist": ["*@billing.example.net", "maria@example.org"]
  }'
```

| Setting | Does |
| --- | --- |
| `accept_from` | Whose mail reaches the inbox: `anyone`; `verified`, senders whose domain vouches for the From address (plus owners, the allowlist and known threads); or `allowlist`, owners, the allowlist and known threads only. The rest is quarantined. |
| `allowlist` | Up to 500 entries: `name@domain`, or `*@domain` for a domain and its subdomains. |
| `owner_addresses` | Up to 50 more addresses treated as the inbox's owners, besides your team members' sign-in addresses. Ignored on the shared domain. |
| `screening` | Score mail from outside senders for prompt injection and phishing (agent inboxes). |
| `extract_codes` | Pull verification codes and sign-in links out of mail. |
| `send_policy` | `reply_only`; `allowlist`, which adds new conversations with owners and the allowlist (not on the shared domain); or `open`, anyone, once the team is past its first sends. |
| `require_approval` | Every send from the inbox waits for a person. |
| `private_codes` | A code or sign-in link the inbox received cannot be sent to anyone but owners and the allowlist. |
| `send_cap` | Recipients the inbox may send to per UTC day without a person: 1 to 100,000, or `null` for no cap (1 to 50 on the shared domain). |
| `forward_to` | Up to 5 addresses that get a copy of every delivered message except spam: team members' sign-in addresses or owner addresses. A copy that cannot go out right away is retried until it is sent, refused for good, or two days have passed; it is never sent twice. |

A setting that breaks a rule answers `422` with the reason. An inbox-scoped key cannot change these settings (`403 restricted_api_key`), and neither can an agent key. An MCP client can read them but not change them. Only an owner, admin or developer changes them, in the dashboard or with a full-access API key. [Agent safety](/docs/agent-safety) explains what each one does.

## Quarantine

Mail an inbox's rules do not let in is quarantined: kept, listed and releasable, never dropped and never returned to its sender. It fires no `email.received` or `inbox.email.received` until it is released, and agents never see it.

`GET /inboxes/{id}/quarantine` lists the held messages with `id`, `from`, `subject`, `quarantine_reason`, `sender_trust`, `injection_score`, `phishing_score` and `virus_signature`, without content. `POST /inboxes/{id}/quarantine/{email_id}/release` delivers one, and `{ "trust_sender": true }` also adds its sender to the allowlist. Both need a full-access key that is not restricted to an inbox. People release from the inbox's **Needs review** tab, and MCP clients with `receiving:manage` use `release_email`. Who may release which hold is in [Agent safety](/docs/agent-safety).

## Verification codes

`GET /inboxes/{id}/codes/latest` answers the newest verification code or sign-in link the inbox received, so an agent never reads HTML:

```sh
curl "https://api.billionsend.com/inboxes/{id}/codes/latest?from=example.org&wait=30" \
  -H "Authorization: Bearer bs_..."
```

```json
{
  "object": "verification_code",
  "status": "found",
  "kind": "link",
  "code": null,
  "url": "https://app.example.org/verify?token=Qm9vdHN0cmFwLTQ4MjkxMw",
  "link_domain_matches_sender": true,
  "email_id": "155252fb-e93e-45ee-8c19-5080a929c28b",
  "from": "no-reply@example.org",
  "received_at": "2026-10-12T14:03:11.229Z",
  "sender_trust": "external"
}
```

- `kind` is `otp` (code in `code`) or `link` (address in `url`, with `link_domain_matches_sender`).
- `from` narrows it to a sender; `wait` (0 to 50 seconds) waits for one to arrive; `max_age` (60 to 86,400 seconds, 600 by default) skips older codes; `since` skips mail received at or before that time, so pass the `received_at` of a code you already used to wait for the next one.
- `status` is `found`, `none`, `ambiguous` (two codes equally likely, so none is answered) or `timeout`. The answer is always `200`.
- Codes never come from quarantined mail, from senders that failed authentication, or from an inbox with `extract_codes` off. Every read is recorded in the inbox's activity.

## Event stream

`GET /inboxes/events` is a server-sent event stream of everything that happens in your inboxes, the moment it is committed. Events carry the webhook event names (`inbox.email.received`, `inbox.thread.created`, `inbox.draft.created`, `email.received` and the other `inbox.*` events) and the webhook payload's `data`. `GET /inboxes/{id}/events` streams one inbox and ends when that inbox is deleted or expires.

```sh
curl -N "https://api.billionsend.com/inboxes/events?types=inbox.email.received" \
  -H "Authorization: Bearer bs_..." \
  -H "Accept: text/event-stream"
```

```text
retry: 1000

id: 812.40.1790000000
event: inbox.email.received
data: {"type":"inbox.email.received","created_at":"2026-11-15T09:20:30.131Z","inbox_id":"7eeb9517-aed7-40d7-ad65-500be42ed147","data":{"source":"system","inbox_id":"7eeb9517-aed7-40d7-ad65-500be42ed147","thread_id":"...","email_id":"...","email":{}}}

: keepalive
```

- Send the key as a `Bearer` header, as for every request. Browsers' `EventSource` cannot set it: use `fetch` and read the body, or any SSE client that takes headers.
- `types` narrows the stream to some events, comma separated; `/inboxes/{id}/events` still sends `inbox.deleted` and `inbox.expired`, the events that end it. Every event is metadata only, like a webhook: no body, code or link. Read the message with the [receiving](/docs/receiving) endpoints.
- **Resuming.** Every event has an `id`. A client that reconnects with `Last-Event-ID` (or `?last_event_id=`) gets what it missed, in order, before the live events. Events are kept for 24 hours; a reconnect from an older id first gets a `stream.gap` event, which means events may be missing and the lists should be read again.
- A stream starts with no replay when it has no `Last-Event-ID`. It is closed by the server every 10 minutes or so, and when the API restarts: reconnect with the last `id` you saw. `retry: 1000` asks a client to wait a second. A comment line every 15 seconds keeps proxies from closing an idle stream.
- A team-wide key opens `/inboxes/events`. A key restricted to one domain, or to one inbox, opens `/inboxes/{id}/events` for an inbox it can reach. A sending-only key cannot open a stream.
- An agent (a key restricted to one inbox, or an MCP connection) never receives `inbox.email.quarantined`, live or replayed, as it never reads held mail; naming it in `types` is a `403 restricted_api_key`.
- A stream closes within a few seconds once its key is revoked, the person who created the key leaves the team, or its inbox is deleted or expires.
- Each key may hold 5 streams at once on each API process and each team 25; one more answers `429 too_many_streams` with `retry-after`. One stream for the whole team is enough for most agents.

`wait` on `/emails/receiving` and `codes/latest` is woken by the same events, so waiting costs nothing while no mail arrives.

## Inbox-scoped API keys

Give each agent a key that reaches only its own inbox. See [API keys](/docs/api-keys).

```sh
curl -X POST "https://api.billionsend.com/api-keys" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "orders agent",
    "permission": "full_access",
    "inbox_id": "7eeb9517-aed7-40d7-ad65-500be42ed147"
  }'
```

- It needs `permission: "full_access"` and cannot take a `domain_id` too. An inbox holds 5 active keys at most, outside the team's limit of 25.
- The key reads its inbox (threads, emails, drafts, labels, codes, the event stream, and `/emails/receiving` limited to that inbox), replies, forwards, writes drafts and sends them, sends new email from its inbox, and sends from the inbox's address only (`403 restricted_api_key` for another `from`; `550 5.7.1` over SMTP).
- Everything else answers `403 restricted_api_key`: it cannot change safety settings, list or release quarantine, approve drafts, create keys or reach another inbox.
- It stops working when its inbox expires, and deleting the inbox revokes it.

In the dashboard, owners, admins and developers pick the inbox under **Restrict to an inbox** when creating a key.

## Webhooks

Inbox events (`inbox.created`, `inbox.thread.created`, `inbox.email.received`, `inbox.email.sent`, `inbox.email.quarantined`, `inbox.expired`, the `inbox.draft.*` events and more) go only to endpoints that name them, never to an endpoint subscribed to all events. An endpoint can be limited to some inboxes with `inbox_ids`. `email.received` still fires for inbox mail once it is delivered. Payloads: [Webhooks](/docs/concepts/webhooks).

## Activity

Everything done in an inbox is recorded: sends and the rules' decisions, refusals, drafts, approvals, releases, code reads, safety changes, deletions and keys. The inbox's **Activity** tab lists it with who acted: a person, an API key or a connected app. Decisions keep reason codes only, never content, codes or addresses.

## Limits

| Limit | Value |
| --- | --- |
| Inboxes | 3 on Free, 25 on Starter, unlimited on Pro and Scale. |
| Inboxes created per hour | 10 on Free, 60 on Starter, 600 on Pro and Scale. |
| Mail per inbox | 200 accepted messages per rolling hour for an agent inbox, 2,000 for a people inbox. Past that, senders get `452 4.2.2` and try again later. |
| Sends | `send_cap` recipients per UTC day. A new inbox reaches new recipients gradually: 10 on its first day of sending, then 20, 40, 80, 160 and so on, up to the cap. |
| Recipients per send | 50 (`to`, `cc` and `bcc` together); 10 from a shared address. |
| Attachments per send | 10 MiB decoded in all; none from a shared address. |
| Shared domain | 1,000 recipients per UTC day for all your team's shared addresses; a shared inbox unused for 90 days is deleted. |
| Labels | 100 per inbox. |
| Safety lists | 500 allowlist entries, 50 owner addresses, 5 `forward_to` addresses. |
| Inbox-scoped keys | 5 active per inbox. |
| Screening | 200 messages per inbox per day; past it, mail that needs screening is quarantined. |
| Waiting | 50 seconds per request; 20 waits at once per team on each API process. |
| Event streams | 5 per API key and 25 per team at once on each API process; events replay for 24 hours. |
| Drafts and trash | A pending draft expires after 7 days; a trashed thread is deleted after 30. |
| Retention | Inbox mail follows received mail's retention: 30 days. |

Inboxes themselves cost nothing: received mail counts once per message against your receiving limit, never against your sending volume, as in [Receiving](/docs/receiving).

## Dashboard

**Inboxes** in the sidebar lists your inboxes under the **All**, **Agent** and **People** tabs, with what needs attention: drafts to approve, unread threads and messages in quarantine. A pinned **All received** row opens every email your domains received. An inbox's page has four tabs: **Threads** (read, reply and approve drafts in place), **Needs review** (drafts and quarantine), **Safety & rules** and **Activity**.

Any member can work an inbox's threads, approve drafts and release quarantine. Owners, admins and developers can also create, change and delete inboxes, change safety rules, create inbox-scoped keys, delete received mail and switch catch-all. See [team roles](/docs/team-roles).

## MCP

[MCP clients](/docs/mcp) work with inboxes under three permissions: `receiving:read` (read mail, wait for it, read codes, list inboxes, threads, labels and drafts, search threads, read safety rules), `receiving:reply` (reply, forward, send from an inbox, write, send and delete drafts, organize threads and labels) and `receiving:manage` (create, change and delete inboxes, list and release quarantine). An MCP client always sees mail the way an agent does: without held mail and with message text fenced as untrusted. It never approves drafts, and `create_inbox` takes `accept_from` and no other safety setting; it never changes an inbox's safety rules.

## API notes

- Creating an inbox or a draft answers the whole object.
- `email_address` is optional: left out, the inbox gets a random permanent address on the shared domain.
- `kind` defaults to `agent`, so an inbox created without it gets an agent's protections.
- There is no hosted agent: `GET /inboxes/{id}/agent` answers empty `instructions`, `tone` and `actions`, and `PATCH /inboxes/{id}/agent` answers `422`.
- Not supported yet: custom `headers` on replies, forwards and draft sends, and `path` (remote URL) attachments. Each answers `422` unless its value is empty.
- A reply, forward or draft send held by the inbox's rules answers `202` with the draft instead of `200` with the email: check that `object` reads `inbox_draft` before treating the result as sent.
- Inbox errors: `403 inbox_send_policy`, `429 inbox_send_cap_reached`, `403 approval_required`, `403 email_quarantined` and `503 name_review_unavailable` (see [Errors](/docs/api-reference/basics)).
- `inbox.*` webhook events are opt-in; `inbox.thread.assigned` and `inbox.thread.unassigned` are not sent.
