使用教程 · 2026
2026 Mailgun Inbox Placement Test API 怎么接入 CI?
如果账号已启用 Inbox Placement,可在正常 Send API 请求中加入测试键,将自家产品邮件发送与种子列表测试关联起来。本文按 CI 时间线讲解接入、重试、报告排查和独立收件验收,避免把 API 响应或种子报告误当成完整业务闭环。
2026 Mailgun Inbox Placement Test API 怎么接入 CI?如果账号已启用 Inbox Placement,可在正常 Send API 请求中加入测试键,将自家产品邮件发送与种子列表测试关联起来。本文按 CI 时间线讲解接入、重试、报告排查和独立收件验收,避免把 API 响应或种子报告误当成完整业务闭环。
本文目录
截至 2026 年 11 月 20 日,Mailgun 官方说明,同一幂等键在 7 天内重复使用不会创建额外的 Inbox Placement 测试。(Send API 收件位置测试说明) 因此,只要账号已启用 Inbox Placement,你就可以在正常 Send API 请求中加入 o:inbox-placement-test-key,把发送与种子列表测试关联起来;同一活动的网络重试沿用稳定键,而种子报告不能替代自家产品的真实收件与业务闭环验收。
本周建议动作:先在获授权的预发环境接入请求,再把“发送已受理、种子报告生成、测试地址收件、业务流程通过”分成不同检查项。
适合谁看:
CI 维护者:想把自家产品邮件发送和收件位置测试接入自动化流程。
QA 工程师:需要区分种子报告与测试地址实际收到邮件的证据。
独立开发者:希望网络重试时不误建测试,也知道何时才该开启新一轮。
最后更新于 2026 年 11 月 20 日;参数、键限制与报告状态核对自 Mailgun 的Send API 参数文档、Send API 收件位置测试说明和种子测试指南。
接入前:先区分你要证明哪一环
CI 邮件测试常把三个不同问题混在一起:应用是否生成了正确邮件、邮件在种子邮箱中落在哪里、真实测试地址是否能走完注册或重置流程。它们的证据来源不同;如果一个绿色状态被拿来代表全部结果,测试就会给团队一种并不存在的保证。
| 验收目标 | 更合适的测试方式 | 能说明什么 | 不能单独说明什么 |
|---|---|---|---|
| 邮件逻辑正确 | 对应用生成的主题、收件人、正文和链接做断言 | 应用构造出的邮件内容符合预期 | 邮件已送达或落入收件箱 |
| 观察收件位置 | 在获授权的 Mailgun Send API 请求中加入测试键 | Mailgun 种子邮箱的收件位置与报告状态 | 每位真实用户的收件结果 |
| 验证业务闭环 | 向受控测试地址发送,再执行收件、点链接、核对账号状态 | 该测试地址上的端到端流程 | 所有邮箱服务商的普遍表现 |
先确认 Mailgun 账号已启用 Inbox Placement;官方参数文档把该功能列为使用测试键的前置条件。也要确认发送域名、测试模板和预发数据属于你自己的产品或获授权环境。种子副本会跟随正常发送请求进入种子列表,因此不要把生产客户地址当作方便的测试对象;将原收件人限定为预发测试地址,并检查 CI 使用的凭证只具备必要权限。
第一步:在正常发送请求中关联测试
Mailgun Send API 的做法不是先另建一封种子邮件,而是在正常的发送表单请求里加上 o:inbox-placement-test-key。该参数触发 Inbox Placement 测试;原收件人仍按请求处理,Mailgun 会自动向该测试对应的完整种子列表发送副本。请求成功响应只能作为这次 API 调用的记录,不能直接写成“报告已生成”或“用户已收到”。
以下示例使用环境变量,收件人应指向你控制的预发测试地址,而非真实客户:
curl -sS -X POST \
-u "api:${MAILGUN_API_KEY}" \
"https://api.mailgun.net/v3/${MAILGUN_DOMAIN}/messages" \
-F "from=${TEST_FROM}" \
-F "to=${CONTROLLED_TEST_RECIPIENT}" \
-F "subject=${TEST_SUBJECT}" \
-F "html=${TEST_HTML}" \
-F "o:inbox-placement-test-key=${IBP_TEST_KEY}"
先从实际 Send API 请求接入,而不要把另一种“只创建测试”的 API 流程与这个参数混为一谈。你可以把 CI 活动标识写入日志或构建元数据,让请求记录、报告和业务测试结果能对应起来;不要把项目名称当作唯一键,因为同一项目会反复运行。完整字段格式以官方 Send API 参数参考为准。
重试与新一轮:复用键,还是换键?
CI 的网络失败与“我要再做一次新的收件位置测试”不是同一件事。超时后重发同一活动的请求,应继续使用原幂等键;只有计划评估另一轮发送时,才生成新键。Mailgun 官方说明,同键 7 天内重复不会创建新测试,账号同时保存的键最多 100 个;达到上限后,在旧键过期前新测试不会创建。
| 运行情形 | 键的处理 | CI 侧建议 |
|---|---|---|
| 同一次请求网络超时,结果未知 | 保持原键 | 重试请求并记录每次响应,不把重试计为新测试 |
| 同一活动被重复触发 | 仍用该活动的稳定键 | 将活动标识与键映射,避免并行任务各自生成新键 |
| 有意发起新一轮报告 | 生成新的运行键 | 把新键与本轮构建或测试运行关联 |
| 账号疑似达到保存上限 | 不靠换键盲目重发 | 先检查近期键使用与报告,再决定是否延后新测试 |
键应能区分“活动”和“有意的新一轮”,但不应随着每次 CI 重试变化。比如,工作流可将活动标识用于稳定部分,将人为启动的新评估运行标识用于新一轮;具体标识生成规则由你的流水线定义。注意,不要把每次构建尝试号都拼进重试键,否则网络重试可能变成多个新测试,且更快耗尽账号可保存的键。
报告缺失:先核对键,再查种子发送
如果运行结束却没有报告,按证据顺序检查,不要先把空结果判成投递失败:
- 核对测试键。确认本次活动是否在 7 天内用过同一键,以及账号是否达到 100 个键的同时保存上限。两种情况都可能导致你期待的新测试没有创建。
- 核对请求与发送记录。保存 CI 活动标识、请求时间、Send API 响应和使用的测试键,确认请求确实发出且测试参数随请求提交。
- 核对种子列表邮件是否完成发送。Mailgun 的报告指南提醒,种子列表邮件尚未全部发送完成时,应先等发送过程结束再继续排查。
- 再判断 Missing。种子报告中的 Missing 是针对种子邮箱的状态,不等同于“邮件必然丢失”。Mailgun 说明,种子在 24 小时未收到邮件后才标记为 Missing;不要在此之前把等待中的种子当作最终失败。
需要用程序读取结果时,先确认账号实际启用的报告接口与权限,再按Inbox Placement 报告 API 文档核对结果字段。官方文档列出的报告包含种子邮箱状态等信息;报告存在与否、各个种子状态以及应用业务断言是不同层的证据,建议分别落日志,不要只留一个 CI 总状态。
常见问题
Mailgun Send API 怎样触发 Inbox Placement 测试?
先确认账号已启用该功能,再将 o:inbox-placement-test-key 添加到自家产品的正常发送请求。Mailgun 会处理原收件人,并自动将副本发送到测试种子列表;这一步检查的是种子收件位置,不是对所有真实用户收件情况的保证。
CI 重试时怎样避免重复创建测试?
对同一活动保持测试键稳定,超时重试不要重新生成键。官方说明,同一键在 7 天内重复使用不会创建额外测试;账号同时保存键的上限为 100 个。如果确实要开新一轮测试,使用新的运行标识,并把它与本轮 CI 记录对应。
报告暂时没有结果时,先查哪些线索?
先看键是否已在有效期内使用、账户是否达到键保存上限,再确认请求确实携带测试键且种子发送已完成。单个种子未出现结果时不要立即认定邮件丢失:Mailgun 的状态说明以种子等待 24 小时仍未收到作为 Missing 的判定边界。
种子列表显示收到邮件,还需要验收注册流程吗?
需要。种子测试不能证明你自家注册地址收到验证码,也不能替你验证链接是否有效、令牌是否被消费或账号是否成功激活。另用预发环境的受控地址完成一次真实业务流程,并把收件证据、链接操作结果和账号状态断言分别记录。
最后验收:从请求记录走到业务闭环
建议把 CI 时间线拆成相互关联但不互相代替的检查项:
| 时间点 | 保存的证据 | 通过条件 |
|---|---|---|
| 发起前 | 环境、活动标识、测试键、目标收件地址 | 地址属于受控测试环境,键策略明确 |
| 请求后 | Send API 请求记录与响应 | 确认请求已发出,且请求携带测试键 |
| 报告阶段 | Inbox Placement 报告及种子状态 | 报告对应正确活动;未完成状态不提前判失败 |
| 业务验收 | 受控测试地址的实收邮件、链接与账号结果 | 邮件内容可读,验证动作和预期状态都成立 |
场景例子:你的预发注册邮件在种子报告中显示已进入种子邮箱,这只能说明对应测试环境里的种子收件位置。测试工程师仍需用预发测试地址收取注册邮件,打开验证链接,并确认账号从“待验证”变为“已验证”;如果只断言 API 返回成功,邮件可能尚未进入收件箱,业务也可能没有完成。
需要留存邮件内容用于排查时,避免将真实用户姓名、账户资料或个人地址塞进测试模板;使用专用测试数据,并限制报告与原始邮件的访问范围。关于短期测试收件和长期转发地址的区别,可参阅临时邮箱与别名转发的适用边界;测试数据处理也可对照邮件隐私与数据处理说明。
独立收件复测:Mailgun 种子与 Mailtock 分开看
Mailtock 页面提供临时收件箱,用于独立观察发往测试地址的邮件;页面说明临时邮箱默认有效期为 3 小时,可续期但单个邮箱最长 24 小时,地址到期后邮件一并删除。它不是 Mailgun 种子列表的一部分,也不代表 Mailgun 报告、API 接口或投递保证;更适合由你在自家预发注册或通知流程中手动复测,不应被写成 CI 自动化收件端。
如果你只需要在非重要的短期测试中隔离主邮箱,可以在 Mailtock 临时收件箱单独查看测试信,再把邮件实收结果与种子报告并列记录。需要长期找回、涉及支付或政务的账号,或必须回信的流程,应使用你能持续控制的邮箱;临时收件只补足“测试地址是否收到并可读”这项证据,不替代关键账户的长期收件安排。
常见问题
Mailgun Send API 怎么触发 Inbox Placement 测试?
确认账号已启用 Inbox Placement 后,在自家产品或获授权环境的正常 Send API 表单请求中加入 `o:inbox-placement-test-key`。Mailgun 会照常处理原收件人,并自动把测试副本发往该测试的完整种子列表;这不是单封邮件必定进入所有真实用户收件箱的保证。([help.mailgun.com](https://help.mailgun.com/hc/en-us/articles/54905297954587-Running-an-Inbox-Placement-Test-via-the-Send-API))
CI 重试怎样避免重复创建 Inbox Placement 测试?
把同一活动或测试运行的稳定标识作为幂等键,网络超时后重试继续使用原键;只有你有意发起一轮新测试时才换新键。Mailgun 文档说明,同一键在 7 天内重复使用不会新增测试,账号同时保存的键最多为 100 个,达到上限时新测试会受阻。([help.mailgun.com](https://help.mailgun.com/hc/en-us/articles/54905297954587-Running-an-Inbox-Placement-Test-via-the-Send-API))
Mailgun Inbox Placement 报告没有结果,先排查什么?
先确认键是否在 7 天有效窗口内用过、账号是否已达到 100 个键的保存上限,再检查本次邮件是否确实发到种子列表所需地址,以及发送是否完成。报告里的 Missing 不是立即确认丢信;Mailgun 说明种子在 24 小时未收到邮件后才标记为 Missing。([help.mailgun.com](https://help.mailgun.com/hc/en-us/articles/4412988835867-Sending-a-seed-test-with-Inbox-Placement))
种子列表显示邮件已收到,还要测注册验证码流程吗?
要。种子报告说明测试副本在种子邮箱中的位置,不证明你的注册地址收到邮件,也不证明验证码解析、链接跳转、令牌有效期或账号状态更新正确。用自家预发环境的受控地址再走一遍注册或密码重置,并分别记录邮件实收与业务状态断言。
本文提供购物收信安排建议,不替代商家的订单、退订或隐私处理说明。具体入口与处理时限以对应服务的规则为准。