Skip to content
Tutorials

通过 API 实现即时收件箱：创建、使用与安全到期

| | 3 分钟阅读
通过 API 实现即时收件箱：创建、使用与安全到期
Instant Inbox via API: Create, Use, and Expire Safely

当你的工作流程需要立即获得一个邮件地址时，等待人工邮箱或重复使用共享测试邮箱是导致测试不稳定、密钥泄露和令人困惑的”这是哪次运行？“调试问题的最快途径。

通过 API 实现即时收件箱颠覆了这种模式。你可以为单一目的（一次测试运行、一次验证尝试、一个智能体任务）配置一个全新的临时收件箱，将收到的邮件作为结构化 JSON 消费，然后让收件箱在短暂、有意的生命周期后过期。

本指南展示了一种实用、可靠性优先的方法来创建、使用和安全到期即时收件箱，这些模式在 CI、QA 自动化和 LLM 智能体中都能很好地工作。

有关规范的 Mailhook API 合约和确切的请求/响应结构，请查看：mailhook.co/llms.txt

“即时收件箱”的真正含义（不只是”一个随机邮件地址”）

对于自动化和智能体而言，即时收件箱不仅仅是一个语法上有效的地址。它是一个可路由的邮件目的地，具有可查询的句柄、清晰的生命周期语义和确定性的传递机制。

以下是在实践中重要的特性：

  • 可配置：通过 REST API 按需创建收件箱。
  • 隔离：每次运行、尝试或智能体任务使用一个收件箱，因此并行处理是安全的。
  • 机器可读：收到的邮件作为结构化 JSON 传递，因此你可以对字段进行断言，而不是脆弱的 HTML。
  • 可事件化：低延迟通知（webhooks）加上确定性回退（轮询）以确保可靠性。
  • 可到期：明确的 TTL，使收件箱不会成为意外的数据存储。
  • 可认证：webhook 负载应该是可验证的（Mailhook 支持签名负载）。

如果你的”即时收件箱”提供商无法建模生命周期和真实性，你最终会在不可靠的原语基础上重建这些保证。

生命周期：创建、接收、提取、到期

思考即时收件箱的简单方法是将其视为具有合约的短期资源。

一个简单的生命周期图，四个方框从左到右连接：创建收件箱（API）-> 使用地址（注册或触发邮件）-> 接收邮件（webhook 或轮询，JSON）-> 到期和清理（TTL，保留）。每个方框都有一个小图标（加号、信封、webhook 钩、垃圾桶/时钟）。

以下是将生命周期分解为可以实现为代码的阶段：

阶段 你要做的 应该存储什么 可能出现的问题
创建 通过 API 配置新的收件箱资源 inbox_id、email、expires_at（或等效） 重复使用收件箱，无 TTL，运行间冲突
使用 将邮件地址提供给被测系统或智能体任务 关联元数据（运行/尝试 ID） 错误地址，错误环境域
接收 通过 webhook（首选）或轮询（回退）等待到达 传递 ID、消息 ID、最小衍生工件 重复传递，伪造的 webhooks，固定睡眠
提取 确定性地提取最小工件（OTP，魔术链接） 工件哈希、提取值、时间戳 HTML 抓取中断，智能体的提示注入
到期 让收件箱到期并停止接受新工作 审计日志（仅 ID），删除标记 保留蠕变，意外 PII 捕获

步骤 1：通过 API 创建即时收件箱

最稳健的模式是创建一个收件箱并传递一个包含以下两者的对象：

  • 邮件地址（外部系统需要的），以及
  • 收件箱句柄（你的代码用于确定性地检索消息的）。

许多团队称这种模式为”邮件加收件箱句柄”。它防止你的自动化扫描共享邮箱，并使并行运行变得安全。

典型的创建响应在概念上如下所示：

{
  "email": "unique-key@your-inbox-domain",
  "inbox_id": "inbox_...",
  "expires_at": "2026-02-27T22:10:45Z"
}

字段名称因提供商而异，因此将其视为结构，而不是承诺。有关 Mailhook 的确切合约，请参阅 llms.txt。

共享域与自定义域

你的域选择影响可传递性和治理：

  • 共享域最快开始（无需 DNS 工作），非常适合早期 CI 和原型制作。
  • 自定义域支持在需要白名单、更强的环境隔离或更严格的运营控制时很有价值。

Mailhook 支持共享域和自定义域，因此你可以从简单开始，在约束条件改变时升级。

步骤 2：使用内置关联的地址

即时收件箱从关联中获得它们的威力。收件箱已经隔离，但你仍然希望跨日志和重试的可追溯性。

一种实用的方法：

  • 为每个工作流程生成一个 run_id 或 attempt_id。
  • 将该 ID 放入你的内部日志中。
  • 如果你控制发送系统，将其包含在头部或模板变量中（例如，作为内部引用字符串），然后匹配它。

这使调试保持可操作：当运行失败时，你可以快速回答”哪个收件箱，哪个消息，哪次传递？”。

步骤 3：确定性地接收邮件（webhook 优先，轮询回退）

Webhook 优先：即时工作流程的默认选择

Webhooks 是即时收件箱流程的最佳默认选择，因为它们低延迟且并行安全。你的处理程序应该被设计为容忍重试和重复。

关键实践：

  • 验证真实性：如果你的提供商支持签名负载，在解析之前验证它们。
  • 使处理幂等：存储传递标识符（或稳定的消息标识符）并忽略重复。
  • 快速确认：在 webhook 处理程序中做最少的工作，将更深层的处理排队到其他地方。

概念性 webhook 验证流程：

接收 webhook -> 验证原始正文签名 -> 检查时间戳容差 -> 去重 -> 排队 -> 响应 2xx

Mailhook 支持用于安全的签名负载，这对于伪造和重放是真实威胁的智能体工作流程来说是一个大问题。

轮询回退：“仍然成功”的路径

即使有 webhooks，你也希望轮询回退用于：

  • 临时 webhook 停机，
  • 本地开发，
  • 入站 HTTP 受限的 CI 环境。

确定性轮询循环应该：

  • 使用截止时间轮询（不是固定睡眠），
  • 保持”已见”游标以避免重复处理，
  • 当收件箱到期时停止。

概念性轮询伪代码：

const deadline = Date.now() + 60_000;
let cursor = null;

while (Date.now() < deadline) {
  const messages = await listMessages({ inbox_id, cursor });

  const match = findMatch(messages, {
    subjectContains: "Your verification code",
    toEquals: email
  });

  if (match) return match;

  cursor = nextCursor(messages);
  await sleep(500);
}

throw new Error("Timed out waiting for email");

这种风格在 CI 中是稳定的：你要么在预算内收到匹配的消息，要么失败并出现包含 run_id 和 inbox_id 的清晰超时。

步骤 4：只提取你需要的内容（特别是对于 LLM 智能体）

对于测试和智能体任务，你几乎从不需要”像人一样读邮件”。你需要一个工件：

  • OTP 代码
  • 魔术链接
  • 验证 URL
  • 重置链接

将邮件视为不可信输入。邮件可以包含跟踪器、意外的 HTML 和试图操纵下游系统的内容。

推荐的防护措施：

  • 优先使用 JSON 输出中的文本类字段，而不是渲染 HTML。
  • 通过严格边界的窄解析器（正则表达式或 URL 解析器）提取。
  • 在任何获取之前验证出站 URL。

LLM 智能体特定的安全注意事项

如果 LLM 智能体将看到邮件内容，通过约束接口来降低风险：

  • 只向智能体提供最小提取的工件，而不是完整消息。
  • 如果必须提供消息内容，提供最小化的 JSON 视图（仅选定字段）并限制长度。
  • 绝不允许智能体盲目地跟随没有白名单的链接。

这不仅是安全措施，也通过减少歧义来提高智能体可靠性。

步骤 5：安全到期（TTL、排放窗口和保留纪律）

大多数团队将”创建”部分做对了，但将”到期”部分做错了。

安全的到期策略回答三个问题：

  1. 收件箱对新消息有效多长时间？（TTL）
  2. 你保持消息可用于调试多长时间？（保留）
  3. 到期后会发生什么？（硬删除、墓碑或拒绝访问）

即使提供商自动使收件箱到期，你仍然应该将到期视为集成的一等部分。

实际 TTL 建议

默认使用短 TTL，然后仅为真正需要它的工作流程增加。

使用案例 建议的 TTL 原因
注册验证测试（CI） 10 到 30 分钟 足够重试和队列延迟，限制保留蠕变
密码重置测试 15 到 45 分钟 重置邮件可能更慢，有时会重试
LLM 智能体”等待邮件”工具 5 到 20 分钟 保持智能体任务有界并降低泄露风险
手动 QA 调试会话 1 到 4 小时 人类更慢，但仍保持临时

到期清单

  • 当收件箱到期时停止轮询。
  • 在 CI 日志中编辑或避免记录消息正文。
  • 仅存储故障排除所需的标识符（收件箱 ID、消息 ID、时间戳）。
  • 如果你为了调试而持久化消息 JSON，应用保留政策和访问控制。

如果你正在为受监管环境构建，考虑将收件箱视为敏感资源，即使它们是”一次性的”。

防止测试不稳定的可靠性模式

即时收件箱消除了一大类邮件不稳定性，但只有在你保持消费合约紧密时才有效。

常见陷阱和修复：

陷阱 症状 修复
固定睡眠 CI 中的随机超时 基于截止时间的等待（webhook 或轮询）
共享收件箱重用 测试断言错误的消息 每次运行或每次尝试一个收件箱
宽匹配器 “找到邮件”但是错误的 窄匹配：收件人 + 主题意图 + 时间窗口
无去重 OTP 或链接的双重处理 存储并强制幂等键
无 webhook 验证 伪造和重放风险 验证签名负载并拒绝失败关闭

Mailhook 的原语清晰地映射到这些需求：通过 API 创建一次性收件箱、实时 webhook 通知、轮询回退和用于真实性的签名负载。

批处理和高吞吐量运行的实现注意事项

如果你运行大型套件或许多智能体任务，你会关心吞吐量。

两个实际考虑：

  • 批处理邮件处理：在进行回填、重新处理或大型并行运行时，优先批量消费消息。
  • 背压：保持 webhook 处理程序快速，工作排队，并异步处理。

这避免了将你的入站邮件层变成 CI 的瓶颈。

常见问题

什么是即时收件箱？ 即时收件箱是一个一次性的、编程创建的收件箱，可以接收真实邮件并将其传递给你的代码（通常为 JSON），具有清晰的生命周期和检索语义。

如何安全地使用即时收件箱进行注册验证？ 为每次尝试创建新的收件箱，使用 webhooks 快速接收邮件，验证签名负载，仅提取 OTP 或验证链接，然后让收件箱到期。

Webhooks 还是轮询，哪个更好？ Webhooks 通常在延迟和规模方面更好。当 webhooks 临时不可用或入站 HTTP 受限时，轮询仍然有价值作为回退。

一次性收件箱应该存活多长时间？ 对于 CI 和智能体工作流程，保持 TTL 短（通常几分钟，不是几天）。长期存在的收件箱成为共享状态并增加泄露和冲突的机会。

LLM 智能体可以直接读邮件吗？ 可以，但更安全的做法是只给智能体提供最小提取的工件（OTP 或 URL），并将邮件内容视为不可信输入。

试用 Mailhook 进行即时收件箱工作流程

如果你想要一个为自动化和智能体构建的即时收件箱 API，Mailhook 提供一次性收件箱创建、作为结构化 JSON 传递的邮件、实时 webhooks、轮询回退、签名负载和批处理。

开始使用不需要信用卡。

instant inbox email automation API testing AI agents webhook integration

相关文章