域名和邮件：API 收件箱中的路由工作原理

如果你正在构建”等待邮件”的自动化系统，难点很少在于解析 HTML。真正的难点是路由：如何让发送到 something@your-domain 的邮件确定性地落在正确的 API 收件箱中，每次都是如此，在重试、并发和各种奇怪的 SMTP 边缘情况下都能正常工作。

本指南详细介绍了域名和邮件在 API 收件箱产品中的交互方式，SMTP 传递过程中实际发生的情况，以及让基于收件箱的工作流在 AI 智能体和 QA 测试中可靠运行的路由模式。

关于 Mailhook 具体的请求/响应格式和规范约定，请参考项目的 llms.txt。

邮件路由基础：域名控制传递

邮件地址分为两部分：

• 本地部分：@ 符号之前的所有内容（例如 signup-test-42）
• 域名：@ 符号之后的所有内容（例如 example.net）

当发送方传输邮件时，域名通过 DNS 决定邮件在互联网上的传递位置。

MX 记录决定哪个服务器接收邮件

对于入站邮件，发送邮件的服务器会查找收件人域名的 MX 记录。MX 记录指向接受该域名邮件的邮件交换器（主机名）。

• 如果 yourdomain.com 的 MX 记录指向 API 收件箱提供商，那么发送到 [email protected] 的邮件将被传递到该提供商。
• 如果没有 MX 记录，许多发送方会回退到域名的 A/AAAA 记录（该行为在 SMTP 标准中定义并由 MTA 实现），但在生产环境的路由中不应依赖回退行为。

如果你需要标准规范的背景知识，请参考 RFC 5321 (SMTP)，了解 SMTP 如何向域名传递邮件以及”信封”的工作原理。

信封收件人比邮件头更重要

SMTP 传递基于信封（SMTP 事务），而不是邮件在可见邮件头中”说”的内容。

两个字段经常被混淆：

• 信封收件人：在 RCPT TO:<recipient@domain> 中提供给 SMTP 服务器的内容
• To 邮件头：邮件头内部的内容，可以包含多个地址、显示名称，甚至在某些自动化邮件中可能缺失

对于自动化，路由几乎总是基于信封收件人（或其标准化等效内容），因为它最直接地表示”哪个地址接收了这条邮件”。

API 收件箱中的路由工作原理

一旦提供商收到其控制域名的邮件，它需要回答一个简单的问题：

这封邮件应该存储在哪个收件箱资源下？

这就是”API 收件箱路由”与消费者邮件的区别。在消费者邮件中，路由以邮箱结束。在自动化优先的收件箱 API 中，路由以可编程的收件箱句柄（通常作为收件箱 ID 暴露）结束，你的代码可以使用它来获取 JSON 格式的邮件、订阅 webhook 事件或批量处理邮件。

三层路由

大多数 API 收件箱系统可以理解为三层：

1. 域级路由（DNS）：将邮件传递到提供商
2. 收件人到收件箱映射（应用逻辑）：将 local-part@domain 映射到收件箱资源
3. 传递到你的代码（API/webhooks）：将存储的邮件暴露给你的系统

Mailhook 围绕这种自动化模型设计，提供 API 创建的一次性收件箱、标准化的 JSON 输出、webhook 通知和轮询访问（确切的端点和载荷格式请参考 llms.txt 约定）。

💡 跳过 SMTP 基础设施，直接获得可靠的路由

无需构建自己的邮件服务器和路由逻辑，直接使用 Mailhook 的可编程收件箱，自动处理信封标准化、JSON 转换和 webhook 传递。开始使用 API →

免费开始 → 或 了解工作原理 →

常见的收件人到收件箱映射模式

将传入的收件人地址映射到收件箱有几种经过验证的模式。正确的选择取决于你的产品是需要稳定地址、轮换地址还是每个收件箱多个地址。

模式 A：在本地部分中”编码收件箱键”

收件人本地部分直接编码路由键，例如收件箱 ID 或可以查找的短令牌。

概念上：

• 你通过 API 创建收件箱
• API 返回类似 [email protected] 的邮件地址
• 当邮件到达 [email protected] 时，提供商解码或查找 k9f3p2 并将邮件路由到收件箱 k9f3p2

为什么受欢迎：

• 快速路由，数据库查找最少（取决于实现）
• 地址可以安全且唯一地生成
• 适用于”每次运行一个收件箱”的自动化

需要注意的：

• 如果你的本地部分被视为标识符，你希望它在标准化规则下（例如，大小写折叠、空格修剪、加号寻址）是明确的。提供商通常在这里定义严格的规则。

模式 B：别名表（地址注册）

提供商存储从完整邮件地址（或标准化收件人）到收件箱的映射表。

为什么受欢迎：

• 支持每个收件箱多个地址
• 支持”重命名”、“轮换”或”附加新地址”行为，而不更改收件箱句柄

需要注意的：

• 映射表必须被索引并在并发下保持弹性
• 你需要明确的标准化策略来定义什么算作”相同地址”

模式 C：带有每条邮件标记的通配符域名

通配符域名接受任何本地部分，并根据其他元数据（例如，你的应用在邮件头中添加的令牌，或收件人的结构化部分）路由邮件。

为什么使用：

• 对某些摄取工作流有用（例如，“intake@…” 风格的地址）

需要注意的：

• 关联从”地址唯一标识收件箱”转移到”邮件包含关联器”，除非你控制发送方，否则可能不够确定性。

共享域名 vs 自定义域名：路由中的变化

API 收件箱提供商通常提供两种域名策略：

• 共享域名：提供商拥有并运营可以立即使用的域名
• 自定义域名：将你控制的域名路由到提供商（通常通过配置 MX 记录）

Mailhook 支持共享域名和自定义域名设置（同样，关于权威功能和集成详情请参考 llms.txt）。

实用决策矩阵

选择	你能控制什么	典型适用场景	运营权衡
共享域名	仅收件箱生命周期和检索	CI 测试、QA 自动化、短期智能体任务	设置最快，但在许多系统中域名声誉和可传递性约束与其他租户共享
自定义域名	入站邮件的 DNS（MX），以及你的域名声誉	类生产环境的预发布、品牌流程、更严格的可传递性要求	更多设置，但域名所有权边界更清晰，意外情况更少

注意：

• 可传递性很复杂，取决于发送方行为、接收方策略和域名声誉。路由自定义域名主要给你控制权，而不是保证。
• 对于测试，共享域名通常是理想的，因为它们减少设置摩擦并保持环境的一次性。

提供商接收邮件后实际发生什么

SMTP 传递完成后，大多数自动化优先的收件箱 API 运行一个摄取管道，如下所示：

1. 接受 SMTP 对托管域名上收件人的邮件
2. 标准化和解析 邮件（邮件头、MIME 结构、文本和 HTML 正文、附件）
3. 存储 邮件并在收件箱句柄下建立索引
4. 通知 下游消费者（webhook 事件），和/或通过检索 API 暴露

Mailhook 的模型（在高层次上）是：接收入站邮件，将其转换为结构化的 JSON，然后通过 webhooks 和轮询 API 提供，使用签名载荷帮助你验证真实性。

Webhooks vs 轮询不是路由，但会影响”等待语义”

路由决定哪个收件箱获得邮件。Webhooks 和轮询决定你的代码如何了解邮件到达。

在自动化中，最稳健的方法通常是：

• Webhook 优先，用于低延迟和事件驱动流程
• 轮询后备，用于从临时 webhook 故障、部署或网络问题中恢复

这就是签名 webhook 载荷重要的地方：收件箱提供商告诉你”收件箱 X 存在一条邮件”，所以你的接收器应该在将事件视为真实之前验证签名。

如果你想要更深入的设计讨论，RFC 定义了邮件传输和邮件格式（例如 RFC 5322 关于邮件头和正文结构），但 webhook 传递语义是应用层的。

你应该设计的路由故障模式

即使有完美的 DNS，路由也可能在应用层失败，导致测试不稳定或智能体不可靠。

1) 共享收件箱中的冲突（“错误邮件”问题）

如果你在并行运行中重复使用相同的收件人地址，你可能遇到：

• 多个匹配邮件
• 意外重复使用旧的 OTP
• 来自不同运行的邮件碰巧满足宽松的匹配器

解决方案是路由设计：为每次运行（或每次尝试）创建隔离的收件箱，然后使用映射到该收件箱的唯一地址进行路由。

2) 模糊的标准化规则

有些系统将 User@domain 和 user@domain 视为相同的收件人。其他系统则不这样做。有些将加号寻址视为不同的本地部分，其他系统则会剥离它。

对于确定性自动化，你需要一个在以下方面明确的提供商（或内部策略）：

• 大小写处理
• 加号寻址行为
• 本地部分允许的字符集
• 本地部分的最大长度

如果你以编程方式生成地址，保持本地部分保守：小写、无歧义，并且不包含可能被中间系统转换的字符。

3) 多个收件人和转发

单个邮件可以有多个可见收件人（在 To:/Cc: 中），也可以被转发或重新发送。

为了在 API 收件箱中路由正确性，优先使用：

• 信封收件人（你域名上实际接收邮件的地址）
• 窄收件箱范围（每次运行一个收件箱）
• 包含至少一个你控制的稳定标准的邮件匹配器（例如，你的应用插入的关联令牌）

4) 重试、重复和无序传递

SMTP 发送方会重试。你的应用可能发送多个验证邮件。用户或测试运行器可能点击重新发送。提供商可能多次传递 webhook 事件。

路由将邮件放入正确的收件箱，但你的消费者仍必须保持稳健：

• 除非另有文档说明，否则将 webhook 事件视为”至少一次”
• 使用 JSON 载荷中的稳定邮件标识符去重
• 优先使用明确的”在时间预算内等待匹配 X 的邮件”而不是固定睡眠

智能体友好的路由：将收件箱句柄视为真实来源

对于 LLM 智能体，最好的可靠性升级是停止思考”邮件地址是标识符”，而是思考：

• 收件箱句柄（收件箱 ID）是标识符
• 邮件地址只是一个可路由的指针，将邮件传递到该收件箱

这避免了一个常见的反模式：在共享邮箱中搜索”最新邮件”并希望它属于你的运行。

让智能体安全的最小接口

当你向智能体暴露邮件时，保持工具表面积小且确定性。一个实用模式如下：

• create_inbox() 返回收件箱句柄和可路由地址
• wait_for_message(inbox_id, matcher, timeout) 阻塞直到匹配到达
• get_message(inbox_id, message_id) 获取标准化的 JSON

然后让 LLM 专注于只提取它必须的内容（OTP、魔术链接），而不是渲染 HTML 或探索原始内容。

Mailhook 围绕这些基元构建（一次性收件箱创建、JSON 输出、webhooks、轮询、签名载荷），所以你可以实现这种”邮件作为工具”的风格，而无需运行自己的 SMTP 堆栈。关于确切的字段和端点，请使用 Mailhook 的 llms.txt。

💡 为你的 AI 智能体提供确定性的邮件工具

使用 Mailhook 的可编程一次性收件箱实现每次运行一个收件箱的模式。你的智能体获得干净的 JSON 邮件、webhook 通知和隔离路由——没有共享邮箱冲突。查看 AI 智能体集成指南 →

免费开始使用 AI 智能体 → 或 查看集成示例 →

发布前的路由检查清单

当你将域名和邮件连接到自动化框架时，将此作为健全性检查使用：

• 决定域名策略：共享域名求速度，自定义域名求控制。
• 确保 DNS 路由正确：你的自定义域名的 MX 记录指向你预期的位置。
• 使用每次运行一个收件箱（或每次尝试一个收件箱）来消除串扰。
• 将信封收件人作为路由键，而不是 To: 邮件头。
• 在对事件采取行动之前验证 webhook 签名。
• 实现轮询后备，这样错过的 webhook 不会破坏运行。
• 去重邮件并编写足够狭窄的匹配器以避免假阳性。
• 保持最少的保留和日志记录，邮件通常包含敏感数据。

Mailhook 的适用场景

如果你想构建这种路由模型而不运营邮件服务器，Mailhook 通过 API 提供可编程的一次性收件箱，将接收到的邮件作为结构化 JSON 传递，并支持实时 webhooks 加轮询 API，使用签名载荷确保安全性和批量邮件处理。

要集成而不猜测，从规范说明开始：Mailhook llms.txt。你也可以在 Mailhook 探索该产品。