不适合：想凭本地捕获证明邮件已进入外部用户收件箱的人。Mailpit 默认 SMTP 端口是 1025，Web 页面与 API 默认端口是 8025；它们承担不同作用。先核对应用实际连接的地址，再检查 Mailpit 是否保存并解析了邮件，最后验证测试查询条件。SMTP 配置文档与Web 页面和 API 配置文档列出了默认端口。
为自家产品测试注册或验证码邮件的开发者，可用这条排查路径区分发送调用与收件箱证据。
QA 工程师可照步骤复现“测试通过但找不到邮件”的故障。
维护邮件集成的独立开发者，可核对 Mailpit 1.33.1 的解析变化是否影响现有测试。
最后核对于 2026 年 11 月 10 日；版本行为依据Mailpit v1.33.1 官方发布记录、集成测试文档及 API 说明复核。
先区分测试通过、发送调用与邮件入库
“测试成功”可能只代表断言通过、发送方法被调用，或应用拿到了发送接口的响应。只有在 Mailpit 页面或查询 API 中找到本次邮件，才能确认当前实例保存了这封邮件。这些结果不能互相替代。
| 你看到的结果 | 可以确认什么 | 下一步该查什么 |
|---|---|---|
| 测试断言通过 | 测试代码满足了当前断言，不一定发生真实 SMTP 发送 | 检查是否使用了模拟对象、拦截器或测试替身 |
| 发送方法被调用 | 应用进入了发送逻辑 | 核对运行时实际加载的 SMTP 或 HTTP API 配置及调用结果 |
| Mailpit 页面能看到邮件 | 邮件进入了当前页面连接的 Mailpit 实例 | 检查解析后的头部、正文与收件人是否符合预期 |
| 页面有邮件，自动化测试却没找到 | Mailpit 已保存邮件，故障更可能在查询条件或邮件标识 | 对照筛选条件、查询端点与本轮邮件 ID |
从应用实际使用的地址开始排查
Mailpit 的 SMTP 收件与 Web 页面/API 使用不同端口。默认情况下，SMTP 接收端使用 1025，Web UI 与 API 使用 8025；端口可以配置，因此应以当前启动参数和环境变量为准，而不是只看默认值。Mailpit 的发送文档说明了通过 SMTP 和 HTTP API 提交邮件的方式。
| 发送方式 | 应核对的配置 | 常见错位 |
|---|---|---|
| SMTP | 主机名、端口、TLS/STARTTLS、认证信息 | 应用连到了另一个 SMTP 服务，或端口与实例配置不符 |
| HTTP API | API 主机与路径、认证方式、当前环境中的配置值 | 发送请求与查询请求指向不同实例，或两者使用不同认证配置 |
容器化环境容易把地址配错。应用容器内的 localhost 通常指向应用所在容器本身，不会自动指向 Mailpit 容器；宿主机浏览器能打开 Mailpit，也不代表应用容器能用同一地址连接。检查应用运行环境中的服务名、网络别名和端口映射，并在应用日志中记录最终使用的目标地址。不要把密钥写进公开日志。
场景例子：注册测试显示成功，但收件箱为空。先确认本轮测试进程加载的是测试环境配置，而不是本地开发环境变量；再确认 SMTP 主机或 API 地址与浏览器打开的 Mailpit 属于同一实例。否则，你可能在一个实例发信，却在另一个实例找信。
如果走 SMTP，查看应用记录的连接与邮件提交结果，并检查服务端日志；如果走 HTTP API，核对请求地址、响应与认证配置。HTTP 发送接口的认证设置可以与页面及其他 API 的认证设置分开，不能因为页面访问正常，就推断发送接口的认证也正常。具体设置以 Mailpit 的发送和服务配置文档为准。
对照 1.33.1 发布记录检查邮件解析
Mailpit v1.33.1 官方发布记录列出了几项与解析有关的修复：处理非 UTF-8 显示名的地址头；补充现有 Bcc 头中缺少的收件人；在解码非 UTF-8 显示名时维持严格的地址解析；以及拒绝无法解析的邮件，而不是静默丢弃。官方发布记录并未说明这些变化能解释所有邮件缺失，也没有给出可套用到各种环境的统一错误码。
如果问题邮件包含非 UTF-8 显示名、Bcc 或特殊编码附件，保存原始邮件样例，并对照应用发送响应与 Mailpit 服务端日志进行复现。不要仅凭页面上没有邮件，就认定某项解析修复导致故障；也不要自行推断某个状态码必然代表解析失败。
从简单样例开始，每次只改变一个因素。例如先发送普通文本邮件，再单独加入非 UTF-8 显示名或 Bcc 收件人，逐次记录发送结果、原始头部与 Mailpit 页面表现。若要核对原始内容，保存邮件源或查看邮件头；截图无法还原原始 MIME 结构。
用页面与 API 判断是“没入库”还是“没查到”
如果页面能显示邮件，但自动化测试报告未找到，先排查查询过滤或邮件标识。Mailpit API 提供邮件列表与搜索等不同端点：列表用于读取消息，搜索则依据查询条件筛选。API 文档列出了对应接口及参数。
先在页面确认邮件存在，再通过邮件列表 API 查看记录。之后逐项放宽过窄的发件人、收件人、主题或时间筛选。地址别名、大小写差异或时间范围，都可能让记录被过滤掉。测试代码读取的邮件 ID 应来自本轮查询结果，不要复用上一次运行保存的标识。
使用 latest 时也要核对具体端点。v1.33.1 的发布记录提到它可用于 release 与 thumbnail 端点；集成文档也说明了 /view/latest.html 与 /view/latest.txt 这类页面路径。不要把某个端点支持 latest 推广成任意 API 路径都支持。若请求没有匹配邮件，或邮件不含相应内容，这类页面路径可能返回 404；这只能说明该请求没有返回对应内容，不能单独证明 SMTP 发送失败。集成测试文档列出了相关页面行为。
按失败路径执行复测清单
- [ ] 确认测试对象是自家产品或获授权的隔离环境，并记录当前运行环境与 Mailpit 版本。
- [ ] 在应用运行进程中核对实际 SMTP 主机、端口，或 HTTP API 地址；不要只检查配置文件模板。
- [ ] 触发一封新的测试邮件，保存应用日志、请求结果或 SMTP 会话结果；仅记录“发送方法被调用”不足以验收。
- [ ] 在与应用连接的同一 Mailpit 实例页面中查找邮件，再通过邮件列表 API 交叉确认。
- [ ] 页面与 API 都没有记录时，保存原始邮件样例和服务端日志，检查目标实例是否一致，以及邮件是否因解析问题被拒绝。
- [ ] 已有记录但测试找不到时，移除筛选条件重查，并核对本轮邮件 ID、查询端点和认证配置。
- [ ] 修复后分别复测普通邮件、非 UTF-8 显示名及带 Bcc 的自家产品测试，记录邮件是否进入 Mailpit、解析内容是否符合预期。
验收结论要限定范围：Mailpit 中出现邮件，只能证明邮件到达了当前配置的本地测试接收端，并可供测试读取；这不能证明邮件已投递到外部邮箱，也不能证明它进入外部收件箱而非垃圾邮件夹。要检查真实外部投递，需另行测试外部收件地址及其收件结果。
常见故障问答
测试日志显示发送成功，Mailpit 页面却没有记录，先查哪里？
先检查应用进程实际使用的 SMTP 主机与端口，或 HTTP API 地址，确认目标就是当前打开的 Mailpit 实例。接着核对发送响应与服务端日志；如果页面和邮件列表 API 都没有记录，再检查解析问题。发送方法被调用或测试断言通过，都不能单独证明目标实例已保存邮件。
如何确认 1.33.1 的解析拒收与查询漏检不是一回事？
先在页面和邮件列表 API 中确认邮件是否存在。两处都没有记录时，保存原始邮件样例、发送端响应与服务端日志，再对照 v1.33.1 发布记录复现解析拒收；官方说明无法解析的邮件会被拒绝，而非静默丢弃。若页面已有记录、测试仍失败，应优先检查筛选条件和邮件标识。
自动化测试通过 API 查不到刚发出的邮件，该如何继续？
先查询邮件列表，确认是否有新记录；再检查搜索条件、收件人与发件人筛选，以及测试代码使用的邮件 ID。不要默认所有 API 端点都支持相同的 latest 标识；应根据当前使用的端点核对文档，并确认发送与读取指向同一实例。
本地 Mailpit 已显示邮件，能说明外部用户也收到了吗？
不能。Mailpit 本地捕获证明邮件抵达了当前测试接收端，但不覆盖外部服务商的投递结果、垃圾邮件判定或收件箱分类。若产品验收目标包含真实外部收件，就要另行投递到外部测试地址，并在该邮箱侧检查结果；不能把本地 SMTP 测试报告写成外部送达证明。
如果你要验证自家产品的邮件能否进入一个可读取的短期收件端，Tmpkey 可以作为 Mailpit 之外的一种测试方案。其临时收件箱页面说明可免注册使用；使用前应按邮件用途确认有效期与数据边界。临时地址适合短时验证，不适合需要长期找回、持续收信或回复的重要账户；也不能据此承诺所有外部邮件必达。了解相关限制，可查看数据处理说明与服务使用规则。