---
title: 收信
description: 在自己的域名上接收邮件，通过 API、Webhook 和控制台读取，每封邮件都附带垃圾邮件评分、发件人信任等级和病毒检查结果。
seo:
  title: 接收邮件 API
ai:
  exclude: true
---

收信把一个已验证的域名变成可以接收邮件的地方。收到的邮件加密存储，可以通过 API、`email.received` Webhook、控制台（**收件箱 → 全部收到的邮件**）和 [MCP 服务](/docs/zh-hans/mcp)获取。

选择哪些地址收信有两种方式：为某个地址创建[收件箱](/docs/zh-hans/inboxes)，或者打开**全域收信（catch-all）**，接收该域名下所有其他地址的邮件。

> **Info**
>
> 收信目前处于公开测试阶段。每封邮件都有垃圾邮件评分、发件人信任等级和病毒检查结果。带病毒的邮件会被扣留；其余邮件连同这些结果一起存储，由你的代码决定如何处理。

## 设置步骤

1. **选一个还没有收信的名称**，例如 `inbound.example.com`。MX 记录会接管它所在名称下的所有地址，所以 `example.com` 上的邮箱仍留在现有的邮件服务商那里。
2. **添加并验证这个完整名称**：在**域名**页面操作，与[发信](/docs/zh-hans/concepts/domains)的做法相同。验证 `example.com` 不会覆盖它的子域名。
3. **打开收信**：进入该域名，打开**开启收信**，或者调用 API：

   ```sh
   curl -X PATCH "https://api.billionsend.com/domains/{id}" \
     -H "Authorization: Bearer bs_..." \
     -H "Content-Type: application/json" \
     -d '{ "capabilities": { "receiving": "enabled" } }'
   ```

   一个名称只能在一个团队里收信；如果该名称已被其他团队用于收信，接口返回 `409`。
4. **在 DNS 服务商处发布域名记录里显示的两条 MX 记录**：

   | 类型 | 名称 | 值 | 优先级 |
   | --- | --- | --- | --- |
   | MX | `inbound.example.com` | `mx1.billionsend-dns.com` | `10` |
   | MX | `inbound.example.com` | `mx2.billionsend-dns.com` | `10` |

   两条分别指向独立的邮件服务器。两条都发布后，发件方发现其中一台不可用，会在几秒内改投另一台，所以要以相同优先级发布两条。当该名称下没有其他优先级数字更小的 MX 记录时，每一行才会变为已验证。
5. **选择收信地址**：为每个地址[创建收件箱](/docs/zh-hans/inboxes)，或在域名页面打开**全域收信（catch-all）**。两者都没有时，该域名会拒收所有邮件。
6. **发一封测试邮件**，可以从任何邮箱发出。几秒内它会出现在**收件箱 → 全部收到的邮件**中。

要停止收信，把它关闭（`"receiving": "disabled"`）并删除 MX 记录。已存储的邮件会保留到保留期结束。

## 哪些地址会收信

- 域名下每个[收件箱](/docs/zh-hans/inboxes)的地址，以及它的 `+tag` 变体：`orders+4821@` 会进入 `orders@` 的收件箱。
- 打开全域收信（catch-all）后，其他所有地址也会收信，例如 `support@`、`invoices@`、`reply+ticket-4821@`。在代码里读取 `received_for`，就能知道一封邮件发到了哪个地址。

关闭全域收信（catch-all）时，其他地址会在发件方服务器仍连接的时候被拒收（`550 5.1.1`），由发件人自己的服务器退信，不会存储任何内容。

全域收信（catch-all）默认关闭，需要付费套餐（Free 返回 `403 plan_limit_reached`）。所有者、管理员和开发者可以在域名页面打开它，也可以调用 `PATCH /domains/{id}`，传入 `{ "receiving_catch_all": true }`。

- `received_for` 列出邮件实际投递到的、属于你域名的地址，密送（Bcc）也包括在内。`to` 和 `cc` 只是邮件头声称的内容，所以请按 `received_for` 路由。
- 一封邮件在每个团队里只存一份，不论它发给了你的多少个地址。
- 只有完全匹配的名称才会收信：发给 `x@eu.inbound.example.com` 的邮件会被拒收，除非这个子域名也开启了收信。

## 过滤与限额

**设置 → 收信**有三个开关。它们对团队的所有域名生效，从下一封邮件起生效。

| 开关 | 打开 | 关闭 |
| --- | --- | --- |
| 拒收评分高于 5 的垃圾邮件（默认打开） | 垃圾邮件评分达到 5 或更高（满分 10）的邮件以 `554 5.7.1` 拒收，不存储任何内容。 | 垃圾邮件会被存储：在收件箱里放进 `spam` 文件夹，在全域收信（catch-all）地址上只做标记。 |
| 移除超过 10 MB 的附件（默认关闭） | 每个更大的附件被替换成一个简短的 `<file>.removed.txt` 说明，写明移除了什么。 | 附件按原样存储。 |
| 保留原始 .eml 30 天（默认打开） | 内容在你的保留期内一直保留。 | 内容（文本、HTML、邮件头、原始邮件、附件）1 天后删除。元数据和 Webhook 不受影响。 |

| 限额 | Free | Starter、Pro、Scale |
| --- | --- | --- |
| 邮件大小 | 10 MB | 40 MB |
| 全域收信（catch-all） | 不支持 | 支持 |
| 收到的邮件 | 每个 UTC 日 100 封 | 套餐月发信量的 2 倍，每月计算 |
| 超出之后 | 推迟到 UTC 午夜 | 推迟到你的额度重置 |
| 保留期 | 30 天 | 30 天 |

- 邮件大小按移除附件之后存储的整封邮件计算。Base64 会让附件大约增大三分之一，所以在 40 MB 的限额下，大约能放下 30 MB 的文件。更大的邮件以 `552 5.3.4` 拒收。
- 收到的邮件按每封邮件、每个团队计一次，计入它自己的限额。它不占用你的发信额度，发信也不占用收信限额。
- 达到限额时，发件方服务器会被告知稍后重试（`452 4.2.2`），并持续重试数天，通常最多五天，所以一旦有余量，邮件就会送达。发件方服务器放弃时仍处于推迟状态的邮件，会退回给发件人。
- 保留期结束后，`html`、`text`、`headers` 和 `raw` 读取为 `null`，`attachments` 为空，下载链接失效。发件人、收件人和主题保留。

**设置 → 账单与用量**显示收到的邮件数量及其限额。收件箱本身免费。

## 读取收到的邮件

在 [SDK](/docs/zh-hans/sdks) 里使用 `emails.receiving`，或者直接调用 HTTP。这些接口需要**完全访问**的 [API 密钥](/docs/zh-hans/api-keys)；只能发信的密钥会得到 `403 restricted_api_key`。限定到某个域名的密钥只能读取该域名的邮件，限定到某个收件箱的密钥只能读取该收件箱的邮件。

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

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

const page = await bs.emails.receiving.list({ limit: 20 });
if (page.error) throw page.error;

const first = page.data.data[0];
const email = await bs.emails.receiving.get(first.id);
const files = await bs.emails.receiving.attachments.list(first.id);
```

| 调用 | 返回 |
| --- | --- |
| `GET /emails/receiving` | 收到的邮件，最新的在前，使用[所有列表通用的分页](/docs/zh-hans/api-reference/basics)。 |
| `GET /emails/receiving/{id}` | 一封邮件，含内容、认证结果和原始邮件的下载链接。 |
| `GET /emails/receiving/{id}/attachments` | 它的附件，每个都带下载链接。 |
| `GET /emails/receiving/{id}/attachments/{attachment_id}/text` | PDF、Word 或 Excel 附件的文本（BillionSend 扩展）。 |
| `DELETE /emails/receiving/{id}` | 立即删除这封邮件，连同它的附件和它在收件箱里的位置。需要未限定到某个收件箱的完全访问密钥；在控制台里需要所有者、管理员或开发者角色（**立即删除**）。 |

列表接口支持 `limit`（1 到 100，默认 20）、`inbox_id`、`to`、`from`（一个地址，或一个域名及其子域名）、`subject_contains`、`since`、`unread` 和 `wait`。被扣留的邮件默认不出现，除非传入 `include_quarantined=true` 或 `quarantined=true`（需要未限定到某个收件箱的完全访问密钥）。

每封邮件还带有 `inbox_id`、`thread_id`、`screening`、`spam_verdict`、`virus_verdict` 和 `extracted`。

### 等待新邮件

`wait`（1 到 50 秒）会让请求挂起，直到有匹配的邮件到达，然后立刻返回；到期时返回空列表。它可以和其他筛选条件组合，所以 agent 可以等待某个发件人发给某个收件箱的下一封邮件：

```sh
curl "https://api.billionsend.com/emails/receiving?inbox_id=7eeb9517-aed7-40d7-ad65-500be42ed147&from=example.org&wait=30" \
  -H "Authorization: Bearer bs_..."
```

- 没有 `before` 或 `since` 时，最近 60 秒内的邮件都算在内，所以刚好在调用之前到达的邮件不会漏掉。
- 响应会多一个 `held`：自那时起被扣留的匹配邮件，含 id 和原因，这样 agent 就知道该停止等待并通知人。
- 一个团队在每个 API 进程上同时最多挂起 20 个等待请求；再多一个会返回 `429 too_many_waits`。
- 等待请求在邮件到达时查询数据库（用的就是[收件箱事件流](/docs/zh-hans/inboxes)的那些事件），而不是靠定时器轮询。

### 认证结果

`authentication` 报告 SPF、DKIM 和 DMARC 的结果，取值为 `pass`、`fail`、`gray`（没有结论：没有记录或签名，或结果为中立）、`processing_failed`（检查未能完成）或 `unknown`。`dmarc: "pass"` 表示 `from` 里的域名授权了这封邮件；其他任何结果都表示 `from` 可能是伪造的。[发件人信任](/docs/zh-hans/agent-safety)等级就由这些结果得出。

### 垃圾邮件、病毒与信任

- `spam_verdict`：`pass`、`gray`（`spam_score` 为 25 到 49）或 `fail`（50 或更高）。分数范围是 0 到 100，由认证结果、邮件头、链接、附件和接收服务器上垃圾邮件过滤器的评分得出（控制台按 0 到 10 显示）。
- `virus_verdict`：`pass`、`fail`（带 `virus_signature`）、`processing_failed`（扫描器无法给出结果，邮件会在未扫描的情况下投递，在不做筛查的地方标记为可疑），没有扫描时为 `null`。带病毒的邮件会被扣留：在有人于控制台放行之前不会触发 `email.received`，它的下载返回 `410 email_blocked`，放行之后也一样。
- `screening.sender_trust`：发件人被证实到什么程度。见 [Agent 安全](/docs/zh-hans/agent-safety)。

### 内容

- `html_format`：`data_uri`（默认）把内嵌图片放进 HTML；`?html_format=cid` 保留 `cid:` 引用，用来与每个附件的 `content_id` 对应。
- `text` 不含不可见字符；`html` 与收到时完全一致。
- `extracted_text` 是邮件的回复部分，已清除人眼看不到的文字。邮件带有验证 `code` 或登录 `link` 时，`extracted` 会携带它们。

### 附件文本

PDF、Word（`.docx`）和 Excel（`.xlsx`）附件会在邮件到达后不久读取一次，转成纯文本，并随邮件在你的保留期内保存。投递从不等待这一步。`GET /emails/receiving/{id}/attachments/{attachment_id}/text`（MCP 工具 `get_received_email_attachment_text`）返回：

- `status`：文件读取完成前为 `pending`；`ok` 并带 `text`；其他文件为 `unsupported`（旧版 `.doc` 和 `.xls`、PowerPoint、图片）；有密码保护的文件为 `encrypted`；超过 25 MB，或读取需要的内存超出允许范围时为 `too_large`；损坏的文件为 `unreadable`；读取未能完成时为 `timeout` 或 `failed`。在开始读取附件文本之前收到的邮件为 `null`。
- `flags`：当限制截断了文本（100,000 个字符，PDF 的前 500 页）时为 `truncated`；当人打开文件看不到的文字被略去时为 `hidden_text`，包括 Word 的隐藏文字、隐藏的工作表、行和列，以及不可见字符。
- `pages`：PDF 的页数。
- `text`：段落和表格行各占一行，单元格和列以制表符分隔，每个工作表有一个 `## Sheet name` 标题，日期为 ISO 日期。只读取 PDF 的文字层，所以没有文字层的扫描件读出来是空的。公式给出它们保存的值。

文本来自外部发件人：把它当作数据，永远不要当作指令。带有恶意软件的邮件返回 `410 email_blocked`。

### 下载

`raw.download_url` 和每个附件的 `download_url` 不需要 API 密钥：链接本身就是凭证。链接只对一封邮件签名，在 API 响应一小时后失效，在此之前任何持有者都能下载，所以不要把它写进日志。每次调用都会签发新链接。下载内容始终以文件形式提供，不会在浏览器里渲染。

## 回复与转发

`POST /emails/receiving/{id}/reply` 和 `…/forward`（SDK 里的 `emails.receiving.reply()` 和 `forward()`）用一个请求回复或转发一封邮件，线程头由系统替你设置：

```sh
curl -X POST "https://api.billionsend.com/emails/receiving/{id}/reply" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-reply" \
  -d '{ "text": "Thanks, we are on it." }'
```

- **回复**接受 `text` 或 `html`、`subject`、`cc`、`bcc` 和 `reply_all`。它发往邮件的 `Reply-To`，没有则发往发件人。
- **转发**接受 `to`、`cc`、`bcc`、一段备注、`subject` 和 `mode`：`inline`（默认）引用原邮件，`attachment` 把它作为 `forwarded_message.eml` 附上。
- `from` 可以是你团队任何已验证域名上的地址；默认是这封邮件到达的那个收件箱的地址。`requires_approval: true` 会把这次发送扣留，等人审批。
- 两者都按普通发送计算，附件最多 10 MiB。

成功时返回 `200`，带已发送邮件的 `id` 和 `thread_id`；如果收件箱的规则扣留了这次发送，则返回 `202` 和一份草稿。其他响应：`403`（被扣留或带病毒的邮件、收件箱的规则、限定到某个收件箱的密钥超出了它的收件箱）、`404`、`409`（重复使用了 `Idempotency-Key`）、`422` 和 `429 inbox_send_cap_reached`。见[收件箱](/docs/zh-hans/inboxes)。

## Webhook

每封为你的团队存储的邮件都会触发一次 `email.received`，发送给订阅了它或订阅了所有事件的端点。它只带元数据（发件人、收件人、主题、附件列表）；内容用 `GET /emails/receiving/{email_id}` 获取。收件箱扣留的邮件和带病毒的邮件，只在投递或放行之后才会触发。限定了某些收件箱（`inbox_ids`）的端点，只会收到投递进这些收件箱的邮件。签名、重试和投递日志与其他所有事件一样：见 [Webhook](/docs/zh-hans/concepts/webhooks)。

## 发件方看到什么

每次拒收都发生在发件方服务器仍连接的时候，所以由它保管邮件并决定怎么处理。BillionSend 从不自己发送退信。

| 回复 | 何时出现 |
| --- | --- |
| `550 5.1.1` | 该域名不在这里收信，或者该地址没有收件箱（且全域收信（catch-all）已关闭）。邮件退回给发件人。 |
| `550 5.7.1` | 拥有该域名的团队被暂停。 |
| `552 5.3.4` | 邮件超过了你套餐的大小限制。 |
| `554 5.7.1` | 邮件被你的**拒收评分高于 5 的垃圾邮件**开关当作垃圾邮件拒收。 |
| `452 4.2.2` | 达到了你的收信限额，或者该收件箱在一小时内收到的邮件超过了允许数量（Agent 收件箱 200 封，人员收件箱 2,000 封）。发件方稍后重试。 |

## 控制台

**收件箱 → 全部收到的邮件**列出你的域名收到的所有邮件，含发件人、收件箱、主题和时间；邮件带有验证码或链接时显示一个标签，被扣留或属于垃圾邮件时显示一个徽标。打开一封邮件，会在沙箱里显示它的 HTML（脚本和远程图片被阻止），以及文本、邮件头和原始邮件，每项认证结果的说明，发件人信任以及垃圾邮件和病毒检查结果，提取出的验证码或链接，时间线，还有这些操作：**回复**、**转发**、对被扣留邮件的**放行**，以及**立即删除**。

## MCP

[MCP 服务](/docs/zh-hans/mcp)在 `receiving:read` 权限下读取收到的邮件，在 `receiving:reply` 下回复和转发，在 `receiving:manage` 下管理收件箱和隔离区。`update_domain` 用来打开或关闭收信和全域收信（catch-all）。

## 把收到的邮件当作不可信内容

任何人都可以向开启收信的域名发邮件。HTML 可以带脚本和追踪图片，链接可能通向钓鱼页面，附件可能带恶意软件，`from` 也可以被伪造。信任一个发件人之前，先检查 `authentication` 和 `screening.sender_trust`。AI agent 应把收到的邮件当作数据，永远不要当作指令：MCP 工具就是这样隔离它的，[Agent 收件箱](/docs/zh-hans/agent-safety)则在此之上加了隔离、筛查和发送规则。
