---
title: 收件箱
description: 把邮件按会话收进来、再从同一个地址回复的邮箱，可以给 AI Agent 用，也可以给人用，支持安全规则、隔离、审批与实时事件流。
seo:
  title: AI Agent 收件箱
ai:
  exclude: true
---

收件箱是一个邮箱地址：收到的邮件按会话归档，也从同一个地址发信。可以交给 AI agent，由它通过 API、Webhook 或 [MCP 服务](/docs/zh-hans/mcp)读取；也可以交给人，在控制台里阅读。收件箱可以是你的某个[收信域名](/docs/zh-hans/receiving)上的地址，也可以是 BillionSend 共享域名上的地址，后者不需要配置 DNS。

[SDK](/docs/zh-hans/sdks) 以 `inboxes.*` 覆盖了收件箱的所有接口，包括安全规则、隔离、审批和实时事件流。

> **Info**
>
> 收件箱目前处于测试阶段，在控制台的**收件箱**下。

## Agent 还是人

每个收件箱都有一个 `kind`，创建时选定，之后不能更改。这个类型决定各项安全设置的默认值。

| 设置 | Agent | 人员 |
| --- | --- | --- |
| `accept_from` | `verified` | `anyone` |
| `screening` | 开 | 关 |
| `extract_codes` | 开 | 开 |
| `send_policy` | `reply_only` | `open`（共享域名上为 `reply_only`） |
| `require_approval` | 关 | 关 |
| `private_codes` | 开 | 关 |
| `send_cap` | 200（共享域名上为 50） | 无（共享域名上为 50） |

- **`agent`** 是省略 `kind` 时的默认值。发件域名无法为其担保的发件人，邮件会在隔离区等待；其他外部发件人的邮件会接受提示词注入筛查；agent 在已有会话里回复，它发起的新对话会变成草稿，等人审批。见 [Agent 安全](/docs/zh-hans/agent-safety)。
- **`human`** 面向在控制台里阅读的人：所有人的邮件都会投递（认证失败的进入 `spam` 文件夹），不做任何筛查。

带病毒的邮件在所有收件箱里都会被隔离。

## 创建收件箱

在控制台里打开**收件箱**，选择**创建收件箱**。或者调用 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"
  }'
```

用 Node.js SDK：

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

const bs = new BillionSend(); // 读取 BILLIONSEND_API_KEY

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

响应（`201`）是完整的收件箱对象：`id`、`name`、`email_address`、`domain_id`、`kind`、`shared`、`expires_at`、`unread`（含未读邮件的会话数）、`drafts`、`quarantined`、`pending_approval` 等。

| 字段 | 规则 |
| --- | --- |
| `email_address` | 你团队某个已验证且能收信的域名上的地址。会转为小写；`@` 前的部分最多 64 个字母、数字和 `. _ % + -`。之后不能更改。省略它则使用共享域名上的地址。 |
| `username` | 省略 `email_address` 时，是共享域名上 `@` 前的部分；省略它，地址随机生成。若给出你自己某个域名的 `domain_id`，则是该域名上 `@` 前的部分。 |
| `domain_id` | `GET /domains` 返回的一行：你团队的共享子域名（`shared: true`），或你的某个已验证域名。 |
| `name` | 1 到 320 个字符；省略时用地址。 |
| `from_name` | 收件箱发出邮件的显示名，最多 78 个字符：只能是普通名称，不含 `@`、`:`、`<`、`>`、换行、链接或电话号码。 |
| `kind` | `agent`（默认）或 `human`。 |
| `expires_in` | 收件箱何时过期，例如 `1h`、`24h` 或 `7d`；省略则永不过期。 |
| `safety` | 任意安全设置。 |
| `forwarding` | `true` 会在共享域名上添加一个 `receiving_address`，用来把你在别处保留的邮箱转发进这个收件箱。 |

| 响应 | 何时出现 |
| --- | --- |
| `409 validation_error` | 已有其他收件箱使用这个地址。系统不会替你另选名称。 |
| `403 validation_error` | 达到了你套餐的收件箱数量上限。 |
| `429 rate_limit_exceeded` | 最近一小时创建的收件箱过多，或共享域名的名称审核已达到今天的上限。`retry-after` 说明何时重试。 |
| `422 validation_error` | 域名未验证或不收信，`username` 违反规则或被保留，或者某项设置违反规则。 |
| `503 name_review_unavailable` | 共享域名上的名称暂时无法审核。稍后重试。 |

其他调用：

- `GET /inboxes` 列出收件箱，最新的在前（`?kind=agent` 或 `?kind=human` 可以收窄范围）。
- `GET /inboxes/{id}` 读取一个。`/inboxes/{id}/…` 路径里的每个 `{id}`，既可以填收件箱的 id，也可以填它的邮箱地址。
- `PATCH /inboxes/{id}` 修改 `name`、`from_name` 或 `expires_in`。
- `DELETE /inboxes/{id}` 删除收件箱及其会话、草稿和标签，并吊销它的 API 密钥。同时也投递到了其他收件箱或全域收信（catch-all）地址的邮件，会留在那里。

## 地址

### 你自己的域名

自己域名上的收件箱，要求该域名可以[收信](/docs/zh-hans/receiving)：已验证、已启用收信，并且已发布 MX 记录。每封邮件按发件方服务器投递到的地址来分派：

1. 先看有没有地址完全相同的收件箱；
2. 没有的话，对于 `name+tag@`，投到 `name@` 的收件箱；
3. 再没有，如果域名打开了全域收信（catch-all），就进入**全部收到的邮件**，不属于任何收件箱；关闭全域收信（catch-all）时，该地址被拒收（`550 5.1.1`）。

从收件箱的地址发出的邮件，在所有入口都遵守这个收件箱的规则：`POST /emails`、批量接口、SMTP 中继和 MCP。给收件箱用一个你的应用尚未用来发信的地址。

### 共享域名

共享域名上的收件箱不需要 DNS。每个团队在 BillionSend 的共享域名上有自己的子域名，按团队命名。省略 `email_address`，或把共享行的 id 作为 `domain_id` 传入，再用 `username` 指定地址：

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

不带 `username` 时，地址随机生成。用户名在以下情况会被拒绝（`422`）：属于保留名（postmaster、abuse、admin、security、support、noreply、no-reply、billing、hostmaster、webmaster、mailer-daemon、root），以 `fwd-` 开头，或者看起来像知名品牌。已被占用的用户名返回 `409`。

**名称审核。** 你选的用户名、`from_name` 和团队的子域名，在发布前都会经过审核，防止冒充品牌、银行、政府或官方角色的名称。被拒绝的名称返回 `422`。审核暂时无法给出结果时，你会得到 `503 name_review_unavailable`；新团队的子域名会反复重试直到通过，24 小时后团队改用 `team-` 加六个随机字符。一个 UTC 日内被拒绝的名称超过 20 个，或审核超过 200 次，之后到 UTC 午夜前一律返回 `429`。

共享地址遵循它们自己的规则，因为这个域名属于所有团队：

- 除非 `expires_in` 另有设置，它们会一直存在到被删除，并计入你套餐的收件箱数量上限。90 天无人使用的会被删除。
- 在 **Free** 套餐上，以及名称看起来像知名品牌的地址，只能在自己的会话里回复，回复对象限于发件域名为其担保的发件人，以及你团队成员的登录地址。在付费套餐上，人可以从这些地址发起对话；agent 则要满足 `send_policy` 为 `open` 且团队已度过最初几次发送，否则它的新对话会作为草稿等人处理。每封发给陌生人的邮件在发出之前都会做钓鱼检查。被拒绝时返回 `403 inbox_send_policy`。
- 每封邮件最多发给 10 个收件人。一个收件箱每天最多向 50 个收件人发送（`send_cap` 取 1 到 50），你团队所有共享地址合计每个 UTC 日最多触达 1,000 个收件人；超出则返回 `429 inbox_send_cap_reached`。
- `from` 必须与收件箱的地址完全一致，邮件不能带 `scheduled_at`、`reply_to`、附件或自定义邮件头（否则 `422`）。`POST /emails/batch`、群发和 SMTP 中继一律拒绝共享地址。
- `forward_to` 只接受成员的登录地址。

发给共享域名上 `postmaster@` 和 `abuse@` 的邮件会进入 BillionSend，不会进入任何收件箱。

### 把邮箱转发进收件箱

`forwarding: true` 适用于邮件存放在别处的地址，例如 Google Workspace 邮箱。收件箱会得到一个 `receiving_address`，即你团队共享子域名上的一个随机地址：把邮箱转发到那里，收件箱就能收到邮件，并从自己的地址回复。这时域名只需要验证到可以发信即可。

## 过期

`expires_in` 是一个数字加 `h` 或 `d`，范围从 `1h` 到 `365d`；省略则收件箱永不过期。用新的 `expires_in` 发起 `PATCH` 时，从那一刻开始计时，传 `null` 则移除过期时间。`expires_at` 显示它何时结束。

到 `expires_at` 时收件箱停止工作：发给它的邮件被拒收（`550 5.1.1`），读取返回 `404`，它的 API 密钥失效。一小时内它会被删除，先触发 `inbox.expired` Webhook，再触发 `inbox.deleted`。修改过期时间需要开发者、管理员或所有者角色。

## 会话

收件箱里的每封邮件都属于一个会话，一个会话同时包含两个方向：收件箱收到的，和它发出的。

- **回复如何找到所属会话。** 收件箱发出的邮件，其 `References` 头里带有一个会话令牌。回复满足以下任一条件时，会进入同一个会话：带有这个令牌，`In-Reply-To` 指向收件箱发出的某封邮件，或引用了该会话里更早的一封邮件。主题永远不会把邮件并入会话。
- **文件夹。** 一个会话位于一个文件夹：`inbox`、`archive`、`spam`、`sent` 或 `trash`。新邮件会把已归档或已发送的会话移回 `inbox`。`DELETE` 把会话移入 `trash`，30 天后清空。
- **已读状态。** 带 `read` 的 `PATCH` 会标记整个会话。被扣留的邮件不会让会话变为未读。在人员收件箱里，打开会话就标记为已读；在 agent 收件箱里，已读状态由你的 agent 掌握。
- **标签。** 每个收件箱最多 100 个，名称 1 到 64 个字符，颜色写成 `#RRGGBB`。

| 调用 | 作用 |
| --- | --- |
| `GET /inboxes/{id}/threads` | 会话列表，最近有动静的在前。筛选条件：`folders`、`labels`、`read`、`include_quarantined`。 |
| `GET /inboxes/{id}/threads/search` | 同样的筛选条件，外加 `query`（支持 `"exact phrase"` 和 `-excluded`）、`from`、`to`、`cc`、`bcc`、`has_attachment`、`start_date`、`end_date`。 |
| `GET /inboxes/{id}/threads/{thread_id}` | 一个会话。 |
| `PATCH /inboxes/{id}/threads/{thread_id}` | 设置 `read` 或 `folder`。 |
| `POST` / `PUT` / `DELETE …/threads/{thread_id}/labels` | 添加、替换或移除标签。 |
| `DELETE /inboxes/{id}/threads/{thread_id}` | 把会话移入垃圾箱。 |
| `GET /inboxes/{id}/threads/{thread_id}/emails` | 它的邮件，最早的在前。 |

搜索按整词匹配，不区分大小写，范围包括：主题、发件人（地址和显示名）、收件人、收到邮件的正文（含它引用的更早邮件）、附件名，以及 PDF、Word 和 Excel 附件的文本（在这些文本读取完成之后）。中文、日文和韩文文本会被分词。`query` 的每个词都必须在同一封邮件里的某处匹配；`from`、`to`、`cc` 和 `bcc` 接受地址或名称里的词。已发送的邮件按主题、发件人和收件人搜索。

`matched_email_id` 是该会话里最匹配的一封，`highlights` 标出它的主题、发件人和收件人里的匹配词（只有正文或附件名匹配时为 `{}`）。新邮件在到达后一两秒内就能被搜索到。搜索暂时不可用时，调用返回 `503`，带 `search_unavailable` 和 `Retry-After` 头；其他调用照常工作。

会话里的一封邮件带有 `direction`、`from`、`to`、`cc`、`bcc`、`reply_to`、`subject`、`message_id`、`html`、`text`、`attachments`、`read` 和 `received_at`。收到的邮件还有 `extracted_text`（回复部分，已清除隐藏文字）、`screening`、`spam_verdict` 和 `virus_verdict`。

## 从收件箱发信

`POST /inboxes/{id}/emails`（SDK 里是 `inboxes.send()`）一次调用就能从收件箱地址发起一段新对话。

```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": "success@simulator.amazonses.com",
    "subject": "Your order 1042",
    "text": "It ships today. The invoice is attached.",
    "attachments": [{ "filename": "invoice.pdf", "content": "JVBERi0xLjQK..." }]
  }'
```

它接受 `to`、`subject`、`html` 和 / 或 `text`，以及可选的 `cc`、`bcc`、`attachments` 和 `requires_approval`。收件箱的规则与回复时一样做出决定，响应也和回复相同：`200` 带 `{ "id", "thread_id" }`，规则扣留这次发送时（收件箱不能发起对话、过了爬坡期的首次收件人、`requires_approval: true`）返回 `202` 和草稿。限定到某个收件箱的密钥可以为它自己的收件箱调用它。

**附件**与 `POST /emails` 接受的相同：`filename` 和 base64 编码的 `content`，内嵌图片可以再带 `content_type` 和 `content_id`。远程 `path` 返回 `422`。回复、转发、新发送和草稿都支持附件，解码后合计最多 10 MiB（转发还要计入原邮件的文件）；可执行程序和伪装类型的文件返回 `422`，共享域名上的收件箱不支持附件。

## 回复与转发

```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." }'
```

回复发往这封邮件的 `Reply-To`，没有则发往它的发件人。`reply_all` 会把其他 `to` 和 `cc` 地址作为 `cc` 加上；`bcc` 永远不会被复制。一次发送最多 50 个收件人。`…/forward` 必须带 `to`，可以附一段备注，并引用原邮件及其附件，外加你添加的 `attachments`（合计最多 10 MiB）。两者都接受 `attachments`，也接受 `requires_approval: true`，让人来审批这次发送。agent 收件箱发出的回复带有 `Auto-Submitted: auto-replied`。

| 响应 | 含义 |
| --- | --- |
| `200` | 已发送：`{ "id", "thread_id" }`。 |
| `202` | 扣留，等人处理：返回草稿，带 `status: "pending_approval"` 和它的 `approval_reasons`。 |
| `403 inbox_send_policy` | 收件箱的规则直接拒绝这次发送。 |
| `403 email_quarantined` | 这封邮件被隔离，或带有病毒。 |
| `403 restricted_api_key` | 限定到某个收件箱的密钥访问了另一个收件箱。 |
| `429 inbox_send_cap_reached` | 收件箱的每日上限已用完；`retry-after` 计时到 UTC 午夜。 |

要回复任何收到的邮件，不论它在不在收件箱里，请用 [`POST /emails/receiving/{id}/reply`](/docs/zh-hans/receiving)。

## 草稿与审批

草稿可以是独立的（用于一段新对话），也可以是带 `thread_id` 和 `reply_to_email_id` 的回复。它的 `status`：

| `status` | 含义 |
| --- | --- |
| `draft` | 正在撰写；在调用 `…/send` 或到达它的 `send_at` 之前不会被发送。 |
| `pending_approval` | 一次发送被扣留，等待人处理。`approval_reasons` 说明原因。7 天后过期。 |
| `sent` | 已发送；`email_id` 指向那封邮件。 |
| `rejected` | 有人驳回了它。 |
| `expired` | 7 天内无人批准。 |

| 调用 | 作用 |
| --- | --- |
| `POST /inboxes/{id}/drafts` | 创建草稿：`to`、`cc`、`bcc`、`subject`、`text`、`html`、`attachments`，回复还要加 `thread_id` 和 `reply_to_email_id`。回复草稿不会复制收件人，所以发送前要设置 `to`。 |
| `GET /inboxes/{id}/drafts` | 未发送的草稿，最近更新的在前。 |
| `GET` / `PATCH` / `DELETE /inboxes/{id}/drafts/{draft_id}` | 读取、修改（设置 `text` 或 `html` 会替换整个正文，`attachments` 会替换整个列表）或删除草稿；已发送后返回 `409`。 |
| `POST /inboxes/{id}/drafts/{draft_id}/send` | 发送它。成功返回 `200`，带已发送邮件的 `id` 和 `thread_id`；被扣留时返回 `202`；没有收件人时返回 `422`。 |
| `POST /inboxes/{id}/drafts/{draft_id}/reject` | 驳回草稿（仅限审批人）。 |

草稿把 `attachments` 与正文分开加密保存，读回时按位置给出 `id`、`filename`、`content_type` 和 `size`，不返回内容。草稿发送时，附件随邮件一起发出；被扣留的发送会把它携带的文件留在草稿里。草稿一旦发送、被驳回、过期或被删除，它的文件就没有了，30 天的内容清理会删掉残留的部分。

**定时发送。** 在 `POST` 或 `PATCH` 上设置 `send_at`（BillionSend 扩展），草稿会在之后发送，发送身份是设置它的人（编辑定时草稿的内容会让编辑者成为发送身份）：值可以是带时区偏移的 ISO 8601 时间，也可以是相对时间，如 `"in 2 hours"`，最多提前 30 天；已过去的时间会在一分钟内发送，`null` 取消。到那时草稿需要有收件人，而且只有 `draft` 状态可以设置定时：等待审批的草稿返回 `409`。到了 `send_at`，这次发送会像当时发出的一样走完所有规则和限额。发送成功后草稿变为 `sent`；被收件箱的规则扣留则变为 `pending_approval`；被拒绝（设置定时的密钥已被吊销、收件箱已不存在、达到了某个限额）则仍是 `draft`，`send_at` 变回 `null`，拒绝原因的名称写在 `send_error` 里，并触发 `inbox.draft.send_failed` Webhook，它带有 `error: { name, message }`。再次设置定时会清除 `send_error`。带 `send_at` 时，为同一封邮件再创建第二个回复草稿会返回 `409`，而不是返回已有草稿。

**谁来审批。** 控制台里的人，或者团队里未限定到某个收件箱的完全访问 API 密钥，可以通过发送来批准：这次发送会跳过扣留 agent 邮件的那些规则。agent 不能批准：限定到某个收件箱的密钥，或者发送待审草稿的 MCP 客户端，会得到 `403 approval_required`。在控制台里，任何成员都可以在收件箱的**待审核**标签页里批准、编辑或丢弃草稿，有内容在等待时，所有者每天会收到一封邮件。

发送被扣留的原因：

| 原因 | 被扣留是因为 |
| --- | --- |
| `approval_required` | 请求要求由人处理（`requires_approval: true`）。 |
| `require_approval` | 这个收件箱的每次发送都要审批。 |
| `send_policy` | 某个收件人不被收件箱的发送策略允许。 |
| `ramp` | 对一个新建的收件箱来说，今天的新收件人太多。 |
| `private_code` | 邮件里含有收件箱收到的验证码或登录链接。 |
| `loop_guard:<reason>` | 它在回复一封自动邮件（外出自动回复、邮件列表、退信）。 |
| `loop_burst` | 一小时内对同一个地址的自动回复过多。 |
| `reply_to_redirect` | 这封邮件的 Reply-To 指向另一个组织。 |

## 安全设置

`GET /inboxes/{id}/safety` 读取收件箱的规则，`PATCH` 修改其中任何一项：

```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"]
  }'
```

| 设置 | 作用 |
| --- | --- |
| `accept_from` | 谁的邮件可以进入收件箱：`anyone`；`verified`，即发件域名为 From 地址担保的发件人（外加所有者、允许列表和已知会话）；或 `allowlist`，仅限所有者、允许列表和已知会话。其余的进入隔离区。 |
| `allowlist` | 最多 500 项：`name@domain`，或 `*@domain`，表示一个域名及其子域名。 |
| `owner_addresses` | 除团队成员的登录地址之外，最多再有 50 个被视为这个收件箱所有者的地址。在共享域名上被忽略。 |
| `screening` | 对外部发件人的邮件评估提示词注入和钓鱼风险（agent 收件箱）。 |
| `extract_codes` | 从邮件里提取验证码和登录链接。 |
| `send_policy` | `reply_only`；`allowlist`，在此基础上允许与所有者和允许列表发起新对话（共享域名上不可用）；或 `open`，任何人，前提是团队已度过最初几次发送。 |
| `require_approval` | 这个收件箱的每次发送都要等人处理。 |
| `private_codes` | 收件箱收到的验证码或登录链接，只能发给所有者和允许列表里的人。 |
| `send_cap` | 收件箱每个 UTC 日无需人工即可发送的收件人数：1 到 100,000，或 `null` 表示不设上限（共享域名上为 1 到 50）。 |
| `forward_to` | 最多 5 个地址，会收到除垃圾邮件之外每封已投递邮件的副本：团队成员的登录地址或所有者地址。无法立即发出的副本会持续重试，直到发出、被永久拒绝或过了两天；它不会被发送两次。 |

违反规则的设置返回 `422` 并附原因。限定到某个收件箱的密钥不能修改这些设置（`403 restricted_api_key`），agent 密钥也不能。MCP 客户端可以读取它们，但不能修改。只有所有者、管理员或开发者可以修改，方式是在控制台里，或使用完全访问的 API 密钥。每一项的具体作用见 [Agent 安全](/docs/zh-hans/agent-safety)。

## 隔离

收件箱的规则不放行的邮件会被隔离：保留、可列出、可放行，既不会被丢弃，也不会退回给发件人。在放行之前，它不会触发 `email.received` 或 `inbox.email.received`，agent 也永远看不到它。

`GET /inboxes/{id}/quarantine` 列出被扣留的邮件，含 `id`、`from`、`subject`、`quarantine_reason`、`sender_trust`、`injection_score`、`phishing_score` 和 `virus_signature`，不含内容。`POST /inboxes/{id}/quarantine/{email_id}/release` 投递其中一封，加上 `{ "trust_sender": true }` 还会把它的发件人加入允许列表。两者都需要未限定到某个收件箱的完全访问密钥。人在收件箱的**待审核**标签页里放行，带 `receiving:manage` 的 MCP 客户端用 `release_email`。谁可以放行哪一种扣留，见 [Agent 安全](/docs/zh-hans/agent-safety)。

## 验证码

`GET /inboxes/{id}/codes/latest` 返回收件箱最新收到的验证码或登录链接，所以 agent 不需要去读 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` 是 `otp`（验证码在 `code` 里）或 `link`（地址在 `url` 里，附带 `link_domain_matches_sender`）。
- `from` 把范围收窄到某个发件人；`wait`（0 到 50 秒）等待新的一封到达；`max_age`（60 到 86,400 秒，默认 600）跳过更旧的验证码；`since` 跳过在该时间或更早收到的邮件，所以把你已经用过的那个验证码的 `received_at` 传进去，就能等下一个。
- `status` 是 `found`、`none`、`ambiguous`（两个验证码可能性相当，所以一个都不返回）或 `timeout`。响应始终是 `200`。
- 验证码永远不会来自被隔离的邮件、认证失败的发件人，或 `extract_codes` 关闭的收件箱。每次读取都会记录在收件箱的活动里。

## 事件流

`GET /inboxes/events` 是一个服务器推送事件（SSE）流，包含你的收件箱里发生的一切，事件提交的瞬间就会推出。事件沿用 Webhook 的事件名（`inbox.email.received`、`inbox.thread.created`、`inbox.draft.created`、`email.received` 和其他 `inbox.*` 事件），并带有 Webhook 载荷里的 `data`。`GET /inboxes/{id}/events` 只推送一个收件箱的事件，该收件箱被删除或过期时结束。

```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
```

- 密钥用 `Bearer` 头发送，与所有请求一样。浏览器的 `EventSource` 无法设置它：改用 `fetch` 读取响应体，或任何支持自定义头的 SSE 客户端。
- `types` 把流收窄到某些事件，用逗号分隔；`/inboxes/{id}/events` 仍会发送 `inbox.deleted` 和 `inbox.expired`，也就是让它结束的事件。与 Webhook 一样，每个事件都只含元数据：没有正文、验证码或链接。邮件要通过[收信](/docs/zh-hans/receiving)接口读取。
- **断线续传。** 每个事件都有一个 `id`。客户端用 `Last-Event-ID`（或 `?last_event_id=`）重新连接时，会先按顺序收到错过的事件，再接上实时事件。事件保留 24 小时；用更早的 id 重连，会先收到一个 `stream.gap` 事件，意思是事件可能有缺失，应当重新读取列表。
- 没有 `Last-Event-ID` 时，流从头开始，不回放。服务器大约每 10 分钟会关闭一次流，API 重启时也会关闭：用你看到的最后一个 `id` 重连。`retry: 1000` 请客户端等待一秒。每 15 秒一行注释，防止代理关闭空闲的流。
- 团队级密钥可以打开 `/inboxes/events`。限定到某个域名或某个收件箱的密钥，可以为它能访问的收件箱打开 `/inboxes/{id}/events`。只能发信的密钥不能打开流。
- agent（限定到某个收件箱的密钥，或 MCP 连接）永远收不到 `inbox.email.quarantined`，不论实时还是回放，因为它从不读取被扣留的邮件；在 `types` 里指定它会返回 `403 restricted_api_key`。
- 当密钥被吊销、创建密钥的人离开团队，或它的收件箱被删除或过期后，流会在几秒内关闭。
- 每个密钥在每个 API 进程上最多同时持有 5 个流，每个团队 25 个；再多一个返回带 `retry-after` 的 `429 too_many_streams`。对大多数 agent 来说，整个团队用一个流就够了。

`/emails/receiving` 和 `codes/latest` 上的 `wait` 由同样的事件唤醒，所以没有邮件到达时，等待不产生任何开销。

## 限定到收件箱的 API 密钥

给每个 agent 一把只能访问它自己收件箱的密钥。见 [API 密钥](/docs/zh-hans/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"
  }'
```

- 它需要 `permission: "full_access"`，并且不能同时带 `domain_id`。一个收件箱最多有 5 把有效密钥，不计入团队 25 把的上限。
- 这把密钥可以读取它的收件箱（会话、邮件、草稿、标签、验证码、事件流，以及限定到该收件箱的 `/emails/receiving`），回复、转发，撰写并发送草稿，从它的收件箱发送新邮件，并且只能使用该收件箱的地址发信（用别的 `from` 返回 `403 restricted_api_key`；通过 SMTP 则是 `550 5.7.1`）。
- 其他一切都返回 `403 restricted_api_key`：它不能修改安全设置，不能列出或放行隔离邮件，不能批准草稿，不能创建密钥，也不能访问另一个收件箱。
- 收件箱过期时它就停止工作，删除收件箱会吊销它。

在控制台里，所有者、管理员和开发者在创建密钥时，可以在**限定到某个收件箱**下选择收件箱。

## Webhook

收件箱事件（`inbox.created`、`inbox.thread.created`、`inbox.email.received`、`inbox.email.sent`、`inbox.email.quarantined`、`inbox.expired`、`inbox.draft.*` 系列事件等）只发送给明确订阅了它们的端点，不会发送给订阅所有事件的端点。端点可以用 `inbox_ids` 限定到某些收件箱。收件箱的邮件在投递之后，仍会触发 `email.received`。载荷见 [Webhook](/docs/zh-hans/concepts/webhooks)。

## 活动

在收件箱里做的每件事都有记录：发送和规则的决定、拒绝、草稿、审批、放行、验证码读取、安全设置变更、删除和密钥。收件箱的**活动**标签页列出这些记录，并注明是谁操作的：一个人、一把 API 密钥或一个已连接的应用。决定只保留原因代码，不保留内容、验证码或地址。

## 限额

| 限额 | 数值 |
| --- | --- |
| 收件箱数量 | Free 3 个，Starter 25 个，Pro 和 Scale 不限。 |
| 每小时创建的收件箱 | Free 10 个，Starter 60 个，Pro 和 Scale 600 个。 |
| 每个收件箱的邮件量 | agent 收件箱每个滚动小时接收 200 封，人员收件箱 2,000 封。超出后，发件方收到 `452 4.2.2` 并稍后重试。 |
| 发送 | 每个 UTC 日 `send_cap` 个收件人。新收件箱逐步触达新收件人：发送的第一天 10 个，之后 20、40、80、160，依此类推，直到上限。 |
| 每次发送的收件人 | 50（`to`、`cc` 和 `bcc` 合计）；共享地址发出的为 10。 |
| 每次发送的附件 | 解码后合计 10 MiB；共享地址不能带附件。 |
| 共享域名 | 你团队所有共享地址合计每个 UTC 日 1,000 个收件人；90 天未使用的共享收件箱会被删除。 |
| 标签 | 每个收件箱 100 个。 |
| 安全列表 | 500 项允许列表，50 个所有者地址，5 个 `forward_to` 地址。 |
| 限定到收件箱的密钥 | 每个收件箱 5 把有效密钥。 |
| 筛查 | 每个收件箱每天 200 封；超出后，需要筛查的邮件会被隔离。 |
| 等待 | 每个请求 50 秒；每个团队在每个 API 进程上同时 20 个等待。 |
| 事件流 | 每个 API 密钥 5 个、每个团队 25 个，在每个 API 进程上同时存在；事件回放 24 小时。 |
| 草稿与垃圾箱 | 待审草稿 7 天后过期；垃圾箱里的会话 30 天后删除。 |
| 保留期 | 收件箱邮件遵循收信的保留期：30 天。 |

收件箱本身不收费：收到的邮件按每封计一次，计入你的收信限额，从不计入你的发信额度，与[收信](/docs/zh-hans/receiving)里一样。

## 控制台

侧栏里的**收件箱**在**全部**、**Agent** 和**人员**标签页下列出你的收件箱，并显示需要关注的事项：待批准的草稿、未读会话和被隔离的邮件。固定的**全部收到的邮件**一行会打开你的域名收到的所有邮件。收件箱页面有四个标签页：**会话**（就地阅读、回复和批准草稿）、**待审核**（草稿和隔离）、**安全与规则**和**活动**。

任何成员都可以处理收件箱的会话、批准草稿和放行隔离邮件。所有者、管理员和开发者还可以创建、修改和删除收件箱，修改安全规则，创建限定到收件箱的密钥，删除收到的邮件，以及打开全域收信（catch-all）。见[团队角色](/docs/zh-hans/team-roles)。

## MCP

[MCP 客户端](/docs/zh-hans/mcp)通过三项权限使用收件箱：`receiving:read`（读取邮件、等待邮件、读取验证码、列出收件箱、会话、标签和草稿、搜索会话、读取安全规则）、`receiving:reply`（回复、转发、从收件箱发信、撰写、发送和删除草稿、整理会话和标签）以及 `receiving:manage`（创建、修改和删除收件箱，列出并放行隔离邮件）。MCP 客户端看到的邮件始终是 agent 视角：没有被扣留的邮件，邮件文本被标注为不可信。它从不批准草稿，`create_inbox` 只接受 `accept_from`，不接受其他安全设置；它从不修改收件箱的安全规则。

## API 说明

- 创建收件箱或草稿时，返回完整的对象。
- `email_address` 是可选的：省略时，收件箱会在共享域名上得到一个随机的永久地址。
- `kind` 默认为 `agent`，所以不带它创建的收件箱会得到 agent 的各项保护。
- 没有托管的 agent：`GET /inboxes/{id}/agent` 返回空的 `instructions`、`tone` 和 `actions`，`PATCH /inboxes/{id}/agent` 返回 `422`。
- 不支持：回复、转发和草稿发送上的自定义 `headers`，以及 `path`（远程 URL）附件。除非值为空，否则各返回 `422`。
- 被收件箱的规则扣留的回复、转发或草稿发送，返回带草稿的 `202`，而不是带邮件的 `200`：把结果当作已发送之前，先检查 `object` 是否为 `inbox_draft`。
- 收件箱的错误：`403 inbox_send_policy`、`429 inbox_send_cap_reached`、`403 approval_required`、`403 email_quarantined` 和 `503 name_review_unavailable`（见[错误](/docs/zh-hans/api-reference/basics)）。
- `inbox.*` Webhook 事件需要主动订阅；`inbox.thread.assigned` 和 `inbox.thread.unassigned` 不会发送。
