---
title: 收件匣
description: 專為 AI Agent 或真人準備的郵件地址：郵件按會話串歸檔，並從同一個地址回覆，附有安全規則、隔離與核准流程。
seo:
  title: AI Agent 收件匣
ai:
  exclude: true
---

收件匣是一個郵件地址，它把收到的郵件按會話串歸檔，並從同一個地址傳送郵件。可以把它交給 AI Agent，由 Agent 透過 API、Webhook 或 [MCP 伺服器](/docs/zh-hant/mcp)讀取；也可以交給真人，在控制台中閱讀。收件匣可以是你某個[收信網域](/docs/zh-hant/receiving)上的地址，也可以是 BillionSend 共用網域上的地址，後者不需要任何 DNS 設定。

[SDK](/docs/zh-hant/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-hant/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 金鑰。同時也到達另一個收件匣或全收地址的郵件，會留在那邊。

## 地址

### 你自己的網域

你自己網域上的收件匣，要求該網域可以[收信](/docs/zh-hant/receiving)：已驗證、已開啟收信，且已發布 MX 記錄。每封郵件依寄件端伺服器投遞到的地址來分派：

1. 先給地址完全相同的收件匣；
2. 否則，對 `name+tag@`，給 `name@` 的收件匣；
3. 否則，網域的全收開啟時，進入沒有收件匣的**所有收到的郵件**；全收關閉時，該地址會被拒收（`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` 時，地址為隨機產生。username 屬於保留名稱（postmaster、abuse、admin、security、support、noreply、no-reply、billing、hostmaster、webmaster、mailer-daemon、root）、以 `fwd-` 開頭，或看起來像知名品牌時，會被拒絕（`422`）。已被佔用的會回傳 `409`。

**名稱審查。** 選定的 username、`from_name` 和團隊的子網域在發布之前都會經過審查，以阻止冒充品牌、銀行、政府或官方職位的名稱。被拒絕的名稱回傳 `422`。審查暫時無法回應時，你會得到 `503 name_review_unavailable`；新團隊的子網域會不斷重試直到通過，24 小時後，團隊會使用 `team-` 加六個隨機字元。一個 UTC 日內被拒絕的名稱超過 20 個，或審查超過 200 次，回應會是 `429`，直到 UTC 午夜。

共用地址有自己的規則，因為這個網域屬於所有團隊：

- 除非 `expires_in` 另有規定，它們會一直存在直到被刪除，並計入你方案的收件匣數量上限。90 天沒有人使用的地址會被刪除。
- 在 **Free** 方案上，以及名稱看起來像知名品牌的任何地址，它們只能在自己的會話串內回覆，對象限於網域為其背書的寄件者和你團隊成員的登入地址。在付費方案上，真人可以從它們發起對話；當 Agent 的 `send_policy` 為 `open` 且你的團隊已度過最初的傳送階段時，Agent 也可以；否則它的新對話會變成草稿，等真人處理。每封寄給陌生人的郵件在送出之前都會做釣魚檢查。被拒絕時回傳 `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-hant/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`，並觸發帶有 `error: { name, message }` 的 `inbox.draft.send_failed` Webhook。重新排程會清除 `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-hant/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-hant/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` 是一個 server-sent event 串流，內容是你的收件匣裡發生的所有事，在事情提交的那一刻就會送出。事件使用 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-hant/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 個；再多一個會回應 `429 too_many_streams` 並附上 `retry-after`。對大多數 Agent 來說，整個團隊開一個串流就夠了。

`/emails/receiving` 和 `codes/latest` 上的 `wait` 是由同樣的事件喚醒的，所以在沒有郵件到達時，等待不花任何成本。

## 限定收件匣的 API 金鑰

給每個 Agent 一把只能存取它自己收件匣的金鑰。參閱 [API 金鑰](/docs/zh-hant/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-hant/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-hant/receiving)。

## 控制台

側邊欄中的**收件匣**以**全部**、**Agent** 和**真人**分頁列出你的收件匣，並顯示需要處理的事項：待核准的草稿、未讀的會話串和在隔離區的郵件。置頂的**所有收到的郵件**一列會開啟你的網域收到的所有郵件。收件匣的頁面有四個分頁：**會話串**（就地閱讀、回覆和核准草稿）、**待審核**（草稿與隔離）、**安全與規則**和**活動**。

任何成員都可以處理收件匣的會話串、核准草稿和放行隔離。擁有者、管理員和開發者還可以建立、修改和刪除收件匣、更改安全規則、建立限定收件匣的金鑰、刪除收到的郵件，以及開關全收。參閱[團隊角色](/docs/zh-hant/team-roles)。

## MCP

[MCP 用戶端](/docs/zh-hant/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-hant/api-reference/basics)）。
- `inbox.*` Webhook 事件需要主動訂閱；`inbox.thread.assigned` 和 `inbox.thread.unassigned` 不會傳送。
