● Mailpit 不需要注册任何账号——它和 Resend 是完全不同的两类东西 Mailpit 是一个假邮箱服务器只在你本机跑。它是一个开源的 Docker 容器我已经加到 docker-compose.yml用 profile 门控只在本地开发时启动永远不会部署到生产。它的作用 - 本地 Keycloak 发的验证邮件不会真的发到互联网而是全部被 Mailpit 拦截存下来 - 你打开 http://localhost:8025 就能看到一个网页版收件箱里面是所有被拦截的邮件可以直接点邮件里的验证链接 - 这样我就能在本地完整测试注册 → 收验证邮件 → 点链接 → 设置密码整条链路不发一封真邮件、不需要任何账号和密钥 之前本地测不了这条链路是因为本地 Keycloak 只有配了 SMTP 才会开启邮箱验证而配你的真实 Gmail 又会真发邮件。Mailpit 解决的就是这个。 需要你注册的是 Resend——那是给生产环境用的真实发信服务让 xxx.com 的用户真的收到来自 noreplyxxx.com 的邮件。两者分工 ┌──────────┬─────────────────────┬────────────────────────────┐ │ │ Mailpit本地测试 │ Resend生产发信 │ ├──────────┼─────────────────────┼────────────────────────────┤ │ 注册账号 │ 不用 │ 要你去 resend.com 注册 │ ├──────────┼─────────────────────┼────────────────────────────┤ │ 邮件去向 │ 存在本机网页里看 │ 真实送达用户邮箱 │ ├──────────┼─────────────────────┼────────────────────────────┤ │ 费用 │ 免费开源 │ 免费额度 100 封/天 │ └──────────┴─────────────────────┴────────────────────────────┘ 所以你只有一个待办注册 Resend、验证域名 xxx.com加它给的 SPF/DKIM DNS 记录、拿到 API key 填进 infra/.env.production 的 SMTP_PASSWORD。这个不急可以等本地验证做完再弄。文章目录Mailpit 入门为本地开发和自动化测试搭建邮件沙箱什么是 MailpitMailpit 的工作原理Mailpit 的核心功能1. 捕获 SMTP 邮件2. Web 邮件预览3. HTML 邮件兼容性检查4. REST API5. 邮件搜索与标签6. 自动清理邮件使用 Docker 快速启动使用 Docker Compose 集成到项目应用程序如何连接 MailpitNode.js 与 NodemailerSpring BootDjango在 Web UI 中检查邮件HTML 视图Text 视图Headers 视图Raw 视图使用 Mailpit 进行自动化测试获取最新邮件的渲染内容Playwright 测试思路使用 Chaos 测试异常场景SMTP Relay 与真实邮件发送Mailpit 与 MailHog 的区别安全注意事项1. 不要将默认配置直接暴露到公网2. 生产环境不要使用不安全认证模式3. 固定版本并及时升级4. 不要在测试邮件中使用真实敏感数据适用场景与限制适合使用 Mailpit 的场景不适合使用 Mailpit 的场景推荐的项目实践总结Mailpit 入门为本地开发和自动化测试搭建邮件沙箱在开发包含注册验证、密码重置、订单通知或告警邮件的系统时我们通常需要反复测试邮件发送功能。直接连接真实 SMTP 服务存在不少问题测试邮件可能误发给真实用户频繁发送容易触发邮件服务商限流开发人员需要准备真实邮箱和 SMTP 凭证邮件内容、Header 和附件不方便调试自动化测试难以稳定验证邮件是否发送成功CI 环境不适合依赖外部邮件服务。Mailpit 提供了一种更安全、更可控的解决方案在本地或测试环境中运行一个假的 SMTP 服务器应用仍然按照正常方式发送邮件但邮件不会真正投递到互联网而是被 Mailpit 捕获并显示在 Web 页面中。什么是 MailpitMailpit 是一个面向开发者的开源邮件测试工具。它同时提供一个 SMTP 服务器用于接收应用发送的邮件一个 Web UI用于浏览和检查捕获的邮件一套 REST API用于自动化集成测试可选的 POP3、SMTP Relay、Webhook 和邮件质量检查能力。Mailpit 使用 Go 开发可以作为单个静态二进制文件运行也提供多架构 Docker 镜像。默认情况下它在1025端口监听 SMTP 连接在8025端口提供 Web UI 和 API。Mailpit 的定位不是正式邮件服务器而是一个邮件沙箱和 SMTP 测试服务器。它解决的核心问题是让应用正常执行邮件发送逻辑但阻止测试邮件真正离开开发或测试环境。Mailpit 的工作原理Mailpit 的基本工作流程如下┌──────────────────────┐ │ Web Application │ │ │ │ 注册、重置密码、通知等 │ └──────────┬───────────┘ │ SMTP │ localhost:1025 ▼ ┌──────────────────────┐ │ Mailpit │ │ │ │ 接收并存储测试邮件 │ └──────────┬───────────┘ │ HTTP │ localhost:8025 ▼ ┌──────────────────────┐ │ Browser / Tests │ │ │ │ 查看邮件或调用 REST API│ └──────────────────────┘应用程序并不知道自己连接的是测试服务器。对于应用来说Mailpit 与普通 SMTP 服务器没有本质区别SMTP_HOSTmailpit SMTP_PORT1025 SMTP_USERNAME SMTP_PASSWORD SMTP_SECUREfalse应用完成邮件生成和 SMTP 发送后Mailpit 会接收邮件将其存储在本地数据库中并通过 Web UI 和 API 暴露出来。默认配置下Mailpit 的 SMTP 服务不启用加密也不要求认证因此特别适合本地开发和隔离的容器网络。Mailpit 的核心功能1. 捕获 SMTP 邮件应用可以像连接普通邮件服务器一样连接 Mailpit。Mailpit 接收邮件后不会将其投递到真实收件人而是将邮件保存在自己的消息存储中。这意味着即使代码中写的是customerexample.com邮件也不会真正发送到这个地址。2. Web 邮件预览Mailpit 提供现代化的 Web UI可以查看HTML 邮件渲染结果纯文本邮件HTML 源代码原始 MIME 内容邮件 Header发件人、收件人、抄送和密送信息MIME 附件图片附件缩略图。Web UI 还支持高级搜索、消息标签、实时更新和浏览器通知。收到新邮件后页面可以通过 WebSocket 自动更新不需要手动刷新。3. HTML 邮件兼容性检查HTML 邮件在 Gmail、Outlook、Apple Mail 等客户端中的表现可能存在明显差异。Mailpit 可以分析 HTML 邮件使用的 CSS 和 HTML 特性并检查这些特性在不同邮件客户端中的兼容情况。它还可以切换桌面、平板和手机预览检查邮件中的链接检查外部图片生成 HTML 邮件截图验证List-UnsubscribeHeader。这些能力让 Mailpit 不只是一个邮件收件箱还可以用于邮件模板质量检查。4. REST APIMailpit 提供 REST API可用于查询邮件列表搜索邮件读取邮件内容删除邮件修改邮件标签通过 HTTP 发送邮件将邮件释放到预先配置的 SMTP Relay在自动化测试中验证邮件内容。因此测试代码不需要解析 Mailpit 的 Web 页面而可以直接调用结构化 API。5. 邮件搜索与标签当系统产生大量测试邮件时可以按照以下条件进行搜索发件人收件人主题正文内容标签时间范围未读状态。Mailpit 还支持手动标签和自动标签可以用来区分注册邮件、订单邮件、告警邮件等不同类型。6. 自动清理邮件Mailpit 默认会保留最近的 500 封邮件并自动清理更早的消息。这个行为可以通过环境变量进行调整environment:MP_MAX_MESSAGES:5000根据官方文档Mailpit 可以处理每秒约 100200 封通过 SMTP 接收的邮件实际吞吐量取决于 CPU、网络和邮件大小。使用 Docker 快速启动运行 Mailpit 最简单的方法是使用 Dockerdockerrun-d\--namemailpit\--restartunless-stopped\-p8025:8025\-p1025:1025\axllent/mailpit启动完成后功能地址或端口Web UIhttp://localhost:8025REST APIhttp://localhost:8025/apiSMTPlocalhost:1025打开浏览器访问http://localhost:8025即可进入 Mailpit 的邮件列表页面。官方 Docker 镜像支持386、amd64和arm64等架构。生产化或长期使用时可以固定具体版本而不是始终使用latest。使用 Docker Compose 集成到项目在实际项目中通常会将 Mailpit 与应用服务一起写入compose.yamlservices:app:build:context:.depends_on:-mailpitenvironment:SMTP_HOST:mailpitSMTP_PORT:1025SMTP_SECURE:falseports:-3000:3000mailpit:image:axllent/mailpitcontainer_name:mailpitrestart:unless-stoppedvolumes:-./mailpit-data:/dataenvironment:MP_DATABASE:/data/mailpit.dbMP_MAX_MESSAGES:5000ports:-8025:8025在 Docker Compose 网络中应用不能使用localhost访问 Mailpit。应当使用服务名SMTP_HOSTmailpit SMTP_PORT1025其中mailpit是 Compose 服务名称1025是容器内部 SMTP 端口8025只需要暴露给浏览器访问如果宿主机程序不需要直接连接 SMTP可以不映射1025:1025。官方文档也建议当只有同一 Compose 网络中的容器需要访问 SMTP 时可以不将 SMTP 端口暴露到宿主机。应用程序如何连接 MailpitNode.js 与 Nodemailer安装依赖npminstallnodemailer创建 SMTP Transportimportnodemailerfromnodemailer;consttransporternodemailer.createTransport({host:process.env.SMTP_HOST??localhost,port:Number(process.env.SMTP_PORT??1025),secure:false,auth:undefined,});asyncfunctionsendWelcomeEmail(to:string):Promisevoid{awaittransporter.sendMail({from:Example App no-replyexample.com,to,subject:Welcome to Example App,text:Your account has been created.,html:h1Welcome/h1 pYour account has been created./p,});}sendWelcomeEmail(userexample.com).catch((error:unknown){console.error(Failed to send email:,error);process.exitCode1;});执行后邮件会出现在 Mailpit Web UI 中。Spring Boot在application-local.yml中配置spring:mail:host:localhostport:1025username:password:properties:mail:smtp:auth:falsestarttls:enable:false如果 Spring Boot 本身也运行在 Docker Compose 中应将主机名改为spring:mail:host:mailpitDjango可以在开发环境配置中指定 SMTP BackendEMAIL_BACKENDdjango.core.mail.backends.smtp.EmailBackendEMAIL_HOSTlocalhostEMAIL_PORT1025EMAIL_USE_TLSFalseEMAIL_HOST_USEREMAIL_HOST_PASSWORDDEFAULT_FROM_EMAILno-replyexample.com在 Web UI 中检查邮件Mailpit 收到邮件后可以从多个角度检查内容。HTML 视图用于确认页面布局是否正确样式是否生效按钮是否可见链接地址是否正确响应式布局是否合理。Text 视图用于确认邮件是否提供纯文本版本。部分邮件客户端或安全策略可能不会渲染 HTML因此重要邮件应当同时提供 HTML 和 Text 内容。Headers 视图可以检查From To Cc Bcc Reply-To Message-ID Content-Type List-Unsubscribe这对于定位以下问题尤其有用发件人地址错误邮件编码错误缺少 Reply-ToMIME 类型不正确附件名称乱码邮件 Header 没有按预期生成。Raw 视图Raw 视图展示完整的原始邮件内容适合排查 MIME Boundary、Content-Transfer-Encoding 和多部分邮件结构。使用 Mailpit 进行自动化测试仅仅验证邮件发送函数“没有抛出异常”是不够的。更完整的集成测试应该验证应用确实发送了邮件邮件发送给正确的收件人邮件主题正确正文包含预期内容验证链接包含正确 Token附件正确生成每个业务事件只产生一封邮件。Mailpit 的 REST API 可以让测试代码读取已捕获的邮件并对邮件内容进行断言。一个典型测试流程如下清空 Mailpit ↓ 调用注册接口 ↓ 等待邮件进入 Mailpit ↓ 通过 API 查询邮件 ↓ 验证收件人、主题和正文 ↓ 提取邮件中的验证链接 ↓ 访问验证链接并检查结果获取最新邮件的渲染内容Mailpit 提供一个方便的渲染接口http://localhost:8025/view/latest.html获取最新邮件的纯文本版本http://localhost:8025/view/latest.txt还可以附加搜索条件只获取符合条件的最新邮件http://localhost:8025/view/latest.html?queryto:userexample.com如果没有找到匹配邮件接口会返回404。该接口适合 Playwright、Cypress 等端到端测试快速读取邮件正文需要 Header、附件或完整结构时则应使用 REST API。Playwright 测试思路import{expect,test}fromplaywright/test;test(user receives verification email,async({request}){constemailuser-${Date.now()}example.com;constregisterResponseawaitrequest.post(/api/register,{data:{email,password:ExamplePassword123!,},});expect(registerResponse.ok()).toBeTruthy();awaitexpect.poll(async(){constresponseawaitfetch(http://localhost:8025/view/latest.txt?queryto:${email},);if(!response.ok){return;}returnresponse.text();},{timeout:10_000,},).toContain(Verify your account);});这里使用轮询而不是固定等待awaitpage.waitForTimeout(5000);原因是邮件发送通常包含异步队列、数据库事务或后台任务固定等待既慢也容易产生不稳定测试。使用 Chaos 测试异常场景正常发送成功只是邮件系统的一种状态。真实 SMTP 服务还可能返回421服务暂时不可用450邮箱暂时不可用451服务端临时错误550地址不存在或被拒绝认证失败收件人被拒绝。Mailpit 的 Chaos 功能可以在 SMTP 事务的不同阶段返回指定错误用于测试应用的容错能力。可配置的错误触发阶段包括SenderRecipientAuthentication。错误还可以按照概率触发例如让 30% 的收件人阶段返回451从而测试重试队列、错误日志和告警逻辑。这类测试可以验证邮件发送失败后是否正确重试是否设置最大重试次数是否会产生重复邮件永久失败是否进入死信队列临时错误和永久错误是否被区别处理日志是否包含足够的诊断信息。这是 Mailpit 相比简单 SMTP Mock 更有价值的能力之一。SMTP Relay 与真实邮件发送Mailpit 默认只捕获邮件不会向外发送。但它也支持配置 SMTP Relay。配置完成后可以在 Web UI 或 API 中将某封捕获的邮件“释放”到真实 SMTP 服务。工作流如下应用发送邮件 ↓ Mailpit 捕获并预览 ↓ 人工确认邮件内容 ↓ 通过 Relay 发送到真实邮箱SMTP Relay 支持STARTTLSSSL/TLSPlain、Login 和 CRAM-MD5 认证-覆盖发件人设置 Return-Path限制允许发送的收件人阻止特定收件人自动中继全部或部分匹配邮件。Mailpit 还区分了 Relay 和 ForwardingRelay将原始收件人对应的邮件释放到真实 SMTP 服务Forwarding将收到的邮件副本自动转发到预先设置的地址。配置自动中继时必须谨慎。特别是smtp-relay-all它会把所有收到的邮件转发给原始收件人错误配置可能导致测试邮件发送给真实用户。Mailpit 与 MailHog 的区别Mailpit 最初受到 MailHog 启发两者的基本目标相同捕获开发环境中的 SMTP 邮件并通过浏览器查看。对比项MailpitMailHog定位SMTP 与邮件测试平台SMTP 捕获工具Web UI现代化 UI相对传统REST API支持支持HTML 兼容性检查支持能力有限链接检查支持能力有限Chaos 错误注入支持能力有限POP3可选支持通常不使用消息标签支持能力有限SMTP Relay支持支持部分相关能力项目维护状态持续更新已长期缺少活跃开发Mailpit 官方项目说明中明确提到MailHog 已经多年没有活跃开发或安全更新。因此对于新项目Mailpit 通常是更合理的选择。安全注意事项1. 不要将默认配置直接暴露到公网Mailpit 默认SMTP 不需要认证SMTP 不启用加密Web UI 不需要认证。这对于本地开发很方便但不适合直接暴露到公网。一旦公网可以访问外部用户可能查看测试邮件获取密码重置链接获取登录验证码调用 Mailpit API利用 SMTP 服务存储大量邮件在启用 Relay 时尝试发送邮件。Mailpit 支持为 Web UI 和 API 配置 HTTPS 与 Basic Authentication。Web UI 和普通 API 默认共享同一套 HTTP 安全配置。2. 生产环境不要使用不安全认证模式下面的配置只适合受信任的本地测试网络environment:MP_SMTP_AUTH_ACCEPT_ANY:1MP_SMTP_AUTH_ALLOW_INSECURE:1MP_SMTP_AUTH_ALLOW_INSECURE允许在未加密连接中使用 SMTP 认证。在真实网络中认证信息可能以可被截获的形式传输。官方文档要求 SMTP 认证通常应与 STARTTLS 或 SSL/TLS 一起使用。3. 固定版本并及时升级对于 CI、测试服务器或可能被其他网络访问的实例建议固定经过验证的 Mailpit 版本image:axllent/mailpit:v1.30.4而不是长期使用image:axllent/mailpit:latest固定版本可以避免某次镜像更新导致测试环境行为突然变化但同时需要建立依赖更新机制。截至 2026 年 7 月Mailpit 最新发布版本为v1.30.4。该版本修复了与公开 SMTP 实例相关的重要安全问题官方建议升级。4. 不要在测试邮件中使用真实敏感数据即使 Mailpit 运行在本地也不建议在测试邮件中放入真实用户密码真实身份证件银行卡信息生产环境访问 Token真实医疗或财务数据。测试环境应使用虚构或脱敏数据。适用场景与限制适合使用 Mailpit 的场景Mailpit 特别适合本地开发Docker Compose 开发环境注册验证邮件测试密码重置邮件测试邮件模板开发CI 集成测试Playwright 或 Cypress 端到端测试SMTP 异常处理测试微服务邮件通知测试QA 和测试环境邮件拦截。不适合使用 Mailpit 的场景Mailpit 不应被当作正式邮件投递服务企业邮件系统邮件营销平台邮件信誉管理平台SPF、DKIM 和 DMARC 完整投递测试平台大规模生产邮件队列。Mailpit 可以验证“应用生成了怎样的邮件”但不能完全证明这封邮件进入真实互联网后一定能够成功投递。真实投递还受到以下因素影响发件域名信誉SPFDKIMDMARCIP 信誉邮件服务商反垃圾策略发送频率退信率用户投诉率。因此更完整的邮件测试体系通常分为三层第一层单元测试 验证模板生成和业务逻辑 第二层Mailpit 集成测试 验证 SMTP 发送、收件人、主题、正文和附件 第三层真实邮箱冒烟测试 验证真实邮件服务商的最终投递结果推荐的项目实践一个相对稳健的环境配置是环境邮件处理方式Local全部发送到 MailpitCI启动临时 Mailpit 容器并通过 API 断言Test使用带认证的共享 MailpitStaging默认捕获少量邮件经人工确认后 RelayProduction连接正式邮件服务商同时建议使用环境变量切换 SMTP 配置禁止本地环境连接生产 SMTP在 CI 中清理历史邮件使用唯一测试邮箱避免并发测试相互影响使用轮询等待邮件不使用固定 Sleep对收件人、主题、正文、链接和附件分别断言测试临时错误、永久错误和重复发送将 Mailpit 端口限制在开发网络内部对共享测试实例启用认证对邮件模板建立快照或视觉回归测试。总结Mailpit 本质上是在应用和真实邮件服务之间建立了一个可观察、可控制的测试边界。它让开发者可以保留真实 SMTP 发送流程避免测试邮件误发在浏览器中检查 HTML、文本、Header 和附件使用 REST API 编写自动化测试使用 Chaos 模拟 SMTP 异常在确认邮件内容后选择性地 Relay将邮件测试集成到 Docker、CI 和端到端测试中。对于需要开发注册、密码重置、订单通知和告警邮件的项目Mailpit 不应只是一个临时调试工具而可以成为邮件质量门禁的一部分生成邮件 ↓ 捕获邮件 ↓ 内容断言 ↓ 链接检查 ↓ 兼容性检查 ↓ 异常恢复测试 ↓ 允许进入真实投递流程如果项目仍然通过日志打印邮件正文或者由开发人员反复向自己的真实邮箱发送测试邮件引入 Mailpit 通常可以显著提升邮件开发的安全性、可观察性和自动化程度。
● Mailpit 不需要注册任何账号——它和 Resend 是完全不同的两类东西 Mailpit 是一个假邮箱服务器只在你本机跑。它是一个开源的 Docker 容器我已经加到 docker-compose.yml用 profile 门控只在本地开发时启动永远不会部署到生产。它的作用 - 本地 Keycloak 发的验证邮件不会真的发到互联网而是全部被 Mailpit 拦截存下来 - 你打开 http://localhost:8025 就能看到一个网页版收件箱里面是所有被拦截的邮件可以直接点邮件里的验证链接 - 这样我就能在本地完整测试注册 → 收验证邮件 → 点链接 → 设置密码整条链路不发一封真邮件、不需要任何账号和密钥 之前本地测不了这条链路是因为本地 Keycloak 只有配了 SMTP 才会开启邮箱验证而配你的真实 Gmail 又会真发邮件。Mailpit 解决的就是这个。 需要你注册的是 Resend——那是给生产环境用的真实发信服务让 xxx.com 的用户真的收到来自 noreplyxxx.com 的邮件。两者分工 ┌──────────┬─────────────────────┬────────────────────────────┐ │ │ Mailpit本地测试 │ Resend生产发信 │ ├──────────┼─────────────────────┼────────────────────────────┤ │ 注册账号 │ 不用 │ 要你去 resend.com 注册 │ ├──────────┼─────────────────────┼────────────────────────────┤ │ 邮件去向 │ 存在本机网页里看 │ 真实送达用户邮箱 │ ├──────────┼─────────────────────┼────────────────────────────┤ │ 费用 │ 免费开源 │ 免费额度 100 封/天 │ └──────────┴─────────────────────┴────────────────────────────┘ 所以你只有一个待办注册 Resend、验证域名 xxx.com加它给的 SPF/DKIM DNS 记录、拿到 API key 填进 infra/.env.production 的 SMTP_PASSWORD。这个不急可以等本地验证做完再弄。文章目录Mailpit 入门为本地开发和自动化测试搭建邮件沙箱什么是 MailpitMailpit 的工作原理Mailpit 的核心功能1. 捕获 SMTP 邮件2. Web 邮件预览3. HTML 邮件兼容性检查4. REST API5. 邮件搜索与标签6. 自动清理邮件使用 Docker 快速启动使用 Docker Compose 集成到项目应用程序如何连接 MailpitNode.js 与 NodemailerSpring BootDjango在 Web UI 中检查邮件HTML 视图Text 视图Headers 视图Raw 视图使用 Mailpit 进行自动化测试获取最新邮件的渲染内容Playwright 测试思路使用 Chaos 测试异常场景SMTP Relay 与真实邮件发送Mailpit 与 MailHog 的区别安全注意事项1. 不要将默认配置直接暴露到公网2. 生产环境不要使用不安全认证模式3. 固定版本并及时升级4. 不要在测试邮件中使用真实敏感数据适用场景与限制适合使用 Mailpit 的场景不适合使用 Mailpit 的场景推荐的项目实践总结Mailpit 入门为本地开发和自动化测试搭建邮件沙箱在开发包含注册验证、密码重置、订单通知或告警邮件的系统时我们通常需要反复测试邮件发送功能。直接连接真实 SMTP 服务存在不少问题测试邮件可能误发给真实用户频繁发送容易触发邮件服务商限流开发人员需要准备真实邮箱和 SMTP 凭证邮件内容、Header 和附件不方便调试自动化测试难以稳定验证邮件是否发送成功CI 环境不适合依赖外部邮件服务。Mailpit 提供了一种更安全、更可控的解决方案在本地或测试环境中运行一个假的 SMTP 服务器应用仍然按照正常方式发送邮件但邮件不会真正投递到互联网而是被 Mailpit 捕获并显示在 Web 页面中。什么是 MailpitMailpit 是一个面向开发者的开源邮件测试工具。它同时提供一个 SMTP 服务器用于接收应用发送的邮件一个 Web UI用于浏览和检查捕获的邮件一套 REST API用于自动化集成测试可选的 POP3、SMTP Relay、Webhook 和邮件质量检查能力。Mailpit 使用 Go 开发可以作为单个静态二进制文件运行也提供多架构 Docker 镜像。默认情况下它在1025端口监听 SMTP 连接在8025端口提供 Web UI 和 API。Mailpit 的定位不是正式邮件服务器而是一个邮件沙箱和 SMTP 测试服务器。它解决的核心问题是让应用正常执行邮件发送逻辑但阻止测试邮件真正离开开发或测试环境。Mailpit 的工作原理Mailpit 的基本工作流程如下┌──────────────────────┐ │ Web Application │ │ │ │ 注册、重置密码、通知等 │ └──────────┬───────────┘ │ SMTP │ localhost:1025 ▼ ┌──────────────────────┐ │ Mailpit │ │ │ │ 接收并存储测试邮件 │ └──────────┬───────────┘ │ HTTP │ localhost:8025 ▼ ┌──────────────────────┐ │ Browser / Tests │ │ │ │ 查看邮件或调用 REST API│ └──────────────────────┘应用程序并不知道自己连接的是测试服务器。对于应用来说Mailpit 与普通 SMTP 服务器没有本质区别SMTP_HOSTmailpit SMTP_PORT1025 SMTP_USERNAME SMTP_PASSWORD SMTP_SECUREfalse应用完成邮件生成和 SMTP 发送后Mailpit 会接收邮件将其存储在本地数据库中并通过 Web UI 和 API 暴露出来。默认配置下Mailpit 的 SMTP 服务不启用加密也不要求认证因此特别适合本地开发和隔离的容器网络。Mailpit 的核心功能1. 捕获 SMTP 邮件应用可以像连接普通邮件服务器一样连接 Mailpit。Mailpit 接收邮件后不会将其投递到真实收件人而是将邮件保存在自己的消息存储中。这意味着即使代码中写的是customerexample.com邮件也不会真正发送到这个地址。2. Web 邮件预览Mailpit 提供现代化的 Web UI可以查看HTML 邮件渲染结果纯文本邮件HTML 源代码原始 MIME 内容邮件 Header发件人、收件人、抄送和密送信息MIME 附件图片附件缩略图。Web UI 还支持高级搜索、消息标签、实时更新和浏览器通知。收到新邮件后页面可以通过 WebSocket 自动更新不需要手动刷新。3. HTML 邮件兼容性检查HTML 邮件在 Gmail、Outlook、Apple Mail 等客户端中的表现可能存在明显差异。Mailpit 可以分析 HTML 邮件使用的 CSS 和 HTML 特性并检查这些特性在不同邮件客户端中的兼容情况。它还可以切换桌面、平板和手机预览检查邮件中的链接检查外部图片生成 HTML 邮件截图验证List-UnsubscribeHeader。这些能力让 Mailpit 不只是一个邮件收件箱还可以用于邮件模板质量检查。4. REST APIMailpit 提供 REST API可用于查询邮件列表搜索邮件读取邮件内容删除邮件修改邮件标签通过 HTTP 发送邮件将邮件释放到预先配置的 SMTP Relay在自动化测试中验证邮件内容。因此测试代码不需要解析 Mailpit 的 Web 页面而可以直接调用结构化 API。5. 邮件搜索与标签当系统产生大量测试邮件时可以按照以下条件进行搜索发件人收件人主题正文内容标签时间范围未读状态。Mailpit 还支持手动标签和自动标签可以用来区分注册邮件、订单邮件、告警邮件等不同类型。6. 自动清理邮件Mailpit 默认会保留最近的 500 封邮件并自动清理更早的消息。这个行为可以通过环境变量进行调整environment:MP_MAX_MESSAGES:5000根据官方文档Mailpit 可以处理每秒约 100200 封通过 SMTP 接收的邮件实际吞吐量取决于 CPU、网络和邮件大小。使用 Docker 快速启动运行 Mailpit 最简单的方法是使用 Dockerdockerrun-d\--namemailpit\--restartunless-stopped\-p8025:8025\-p1025:1025\axllent/mailpit启动完成后功能地址或端口Web UIhttp://localhost:8025REST APIhttp://localhost:8025/apiSMTPlocalhost:1025打开浏览器访问http://localhost:8025即可进入 Mailpit 的邮件列表页面。官方 Docker 镜像支持386、amd64和arm64等架构。生产化或长期使用时可以固定具体版本而不是始终使用latest。使用 Docker Compose 集成到项目在实际项目中通常会将 Mailpit 与应用服务一起写入compose.yamlservices:app:build:context:.depends_on:-mailpitenvironment:SMTP_HOST:mailpitSMTP_PORT:1025SMTP_SECURE:falseports:-3000:3000mailpit:image:axllent/mailpitcontainer_name:mailpitrestart:unless-stoppedvolumes:-./mailpit-data:/dataenvironment:MP_DATABASE:/data/mailpit.dbMP_MAX_MESSAGES:5000ports:-8025:8025在 Docker Compose 网络中应用不能使用localhost访问 Mailpit。应当使用服务名SMTP_HOSTmailpit SMTP_PORT1025其中mailpit是 Compose 服务名称1025是容器内部 SMTP 端口8025只需要暴露给浏览器访问如果宿主机程序不需要直接连接 SMTP可以不映射1025:1025。官方文档也建议当只有同一 Compose 网络中的容器需要访问 SMTP 时可以不将 SMTP 端口暴露到宿主机。应用程序如何连接 MailpitNode.js 与 Nodemailer安装依赖npminstallnodemailer创建 SMTP Transportimportnodemailerfromnodemailer;consttransporternodemailer.createTransport({host:process.env.SMTP_HOST??localhost,port:Number(process.env.SMTP_PORT??1025),secure:false,auth:undefined,});asyncfunctionsendWelcomeEmail(to:string):Promisevoid{awaittransporter.sendMail({from:Example App no-replyexample.com,to,subject:Welcome to Example App,text:Your account has been created.,html:h1Welcome/h1 pYour account has been created./p,});}sendWelcomeEmail(userexample.com).catch((error:unknown){console.error(Failed to send email:,error);process.exitCode1;});执行后邮件会出现在 Mailpit Web UI 中。Spring Boot在application-local.yml中配置spring:mail:host:localhostport:1025username:password:properties:mail:smtp:auth:falsestarttls:enable:false如果 Spring Boot 本身也运行在 Docker Compose 中应将主机名改为spring:mail:host:mailpitDjango可以在开发环境配置中指定 SMTP BackendEMAIL_BACKENDdjango.core.mail.backends.smtp.EmailBackendEMAIL_HOSTlocalhostEMAIL_PORT1025EMAIL_USE_TLSFalseEMAIL_HOST_USEREMAIL_HOST_PASSWORDDEFAULT_FROM_EMAILno-replyexample.com在 Web UI 中检查邮件Mailpit 收到邮件后可以从多个角度检查内容。HTML 视图用于确认页面布局是否正确样式是否生效按钮是否可见链接地址是否正确响应式布局是否合理。Text 视图用于确认邮件是否提供纯文本版本。部分邮件客户端或安全策略可能不会渲染 HTML因此重要邮件应当同时提供 HTML 和 Text 内容。Headers 视图可以检查From To Cc Bcc Reply-To Message-ID Content-Type List-Unsubscribe这对于定位以下问题尤其有用发件人地址错误邮件编码错误缺少 Reply-ToMIME 类型不正确附件名称乱码邮件 Header 没有按预期生成。Raw 视图Raw 视图展示完整的原始邮件内容适合排查 MIME Boundary、Content-Transfer-Encoding 和多部分邮件结构。使用 Mailpit 进行自动化测试仅仅验证邮件发送函数“没有抛出异常”是不够的。更完整的集成测试应该验证应用确实发送了邮件邮件发送给正确的收件人邮件主题正确正文包含预期内容验证链接包含正确 Token附件正确生成每个业务事件只产生一封邮件。Mailpit 的 REST API 可以让测试代码读取已捕获的邮件并对邮件内容进行断言。一个典型测试流程如下清空 Mailpit ↓ 调用注册接口 ↓ 等待邮件进入 Mailpit ↓ 通过 API 查询邮件 ↓ 验证收件人、主题和正文 ↓ 提取邮件中的验证链接 ↓ 访问验证链接并检查结果获取最新邮件的渲染内容Mailpit 提供一个方便的渲染接口http://localhost:8025/view/latest.html获取最新邮件的纯文本版本http://localhost:8025/view/latest.txt还可以附加搜索条件只获取符合条件的最新邮件http://localhost:8025/view/latest.html?queryto:userexample.com如果没有找到匹配邮件接口会返回404。该接口适合 Playwright、Cypress 等端到端测试快速读取邮件正文需要 Header、附件或完整结构时则应使用 REST API。Playwright 测试思路import{expect,test}fromplaywright/test;test(user receives verification email,async({request}){constemailuser-${Date.now()}example.com;constregisterResponseawaitrequest.post(/api/register,{data:{email,password:ExamplePassword123!,},});expect(registerResponse.ok()).toBeTruthy();awaitexpect.poll(async(){constresponseawaitfetch(http://localhost:8025/view/latest.txt?queryto:${email},);if(!response.ok){return;}returnresponse.text();},{timeout:10_000,},).toContain(Verify your account);});这里使用轮询而不是固定等待awaitpage.waitForTimeout(5000);原因是邮件发送通常包含异步队列、数据库事务或后台任务固定等待既慢也容易产生不稳定测试。使用 Chaos 测试异常场景正常发送成功只是邮件系统的一种状态。真实 SMTP 服务还可能返回421服务暂时不可用450邮箱暂时不可用451服务端临时错误550地址不存在或被拒绝认证失败收件人被拒绝。Mailpit 的 Chaos 功能可以在 SMTP 事务的不同阶段返回指定错误用于测试应用的容错能力。可配置的错误触发阶段包括SenderRecipientAuthentication。错误还可以按照概率触发例如让 30% 的收件人阶段返回451从而测试重试队列、错误日志和告警逻辑。这类测试可以验证邮件发送失败后是否正确重试是否设置最大重试次数是否会产生重复邮件永久失败是否进入死信队列临时错误和永久错误是否被区别处理日志是否包含足够的诊断信息。这是 Mailpit 相比简单 SMTP Mock 更有价值的能力之一。SMTP Relay 与真实邮件发送Mailpit 默认只捕获邮件不会向外发送。但它也支持配置 SMTP Relay。配置完成后可以在 Web UI 或 API 中将某封捕获的邮件“释放”到真实 SMTP 服务。工作流如下应用发送邮件 ↓ Mailpit 捕获并预览 ↓ 人工确认邮件内容 ↓ 通过 Relay 发送到真实邮箱SMTP Relay 支持STARTTLSSSL/TLSPlain、Login 和 CRAM-MD5 认证-覆盖发件人设置 Return-Path限制允许发送的收件人阻止特定收件人自动中继全部或部分匹配邮件。Mailpit 还区分了 Relay 和 ForwardingRelay将原始收件人对应的邮件释放到真实 SMTP 服务Forwarding将收到的邮件副本自动转发到预先设置的地址。配置自动中继时必须谨慎。特别是smtp-relay-all它会把所有收到的邮件转发给原始收件人错误配置可能导致测试邮件发送给真实用户。Mailpit 与 MailHog 的区别Mailpit 最初受到 MailHog 启发两者的基本目标相同捕获开发环境中的 SMTP 邮件并通过浏览器查看。对比项MailpitMailHog定位SMTP 与邮件测试平台SMTP 捕获工具Web UI现代化 UI相对传统REST API支持支持HTML 兼容性检查支持能力有限链接检查支持能力有限Chaos 错误注入支持能力有限POP3可选支持通常不使用消息标签支持能力有限SMTP Relay支持支持部分相关能力项目维护状态持续更新已长期缺少活跃开发Mailpit 官方项目说明中明确提到MailHog 已经多年没有活跃开发或安全更新。因此对于新项目Mailpit 通常是更合理的选择。安全注意事项1. 不要将默认配置直接暴露到公网Mailpit 默认SMTP 不需要认证SMTP 不启用加密Web UI 不需要认证。这对于本地开发很方便但不适合直接暴露到公网。一旦公网可以访问外部用户可能查看测试邮件获取密码重置链接获取登录验证码调用 Mailpit API利用 SMTP 服务存储大量邮件在启用 Relay 时尝试发送邮件。Mailpit 支持为 Web UI 和 API 配置 HTTPS 与 Basic Authentication。Web UI 和普通 API 默认共享同一套 HTTP 安全配置。2. 生产环境不要使用不安全认证模式下面的配置只适合受信任的本地测试网络environment:MP_SMTP_AUTH_ACCEPT_ANY:1MP_SMTP_AUTH_ALLOW_INSECURE:1MP_SMTP_AUTH_ALLOW_INSECURE允许在未加密连接中使用 SMTP 认证。在真实网络中认证信息可能以可被截获的形式传输。官方文档要求 SMTP 认证通常应与 STARTTLS 或 SSL/TLS 一起使用。3. 固定版本并及时升级对于 CI、测试服务器或可能被其他网络访问的实例建议固定经过验证的 Mailpit 版本image:axllent/mailpit:v1.30.4而不是长期使用image:axllent/mailpit:latest固定版本可以避免某次镜像更新导致测试环境行为突然变化但同时需要建立依赖更新机制。截至 2026 年 7 月Mailpit 最新发布版本为v1.30.4。该版本修复了与公开 SMTP 实例相关的重要安全问题官方建议升级。4. 不要在测试邮件中使用真实敏感数据即使 Mailpit 运行在本地也不建议在测试邮件中放入真实用户密码真实身份证件银行卡信息生产环境访问 Token真实医疗或财务数据。测试环境应使用虚构或脱敏数据。适用场景与限制适合使用 Mailpit 的场景Mailpit 特别适合本地开发Docker Compose 开发环境注册验证邮件测试密码重置邮件测试邮件模板开发CI 集成测试Playwright 或 Cypress 端到端测试SMTP 异常处理测试微服务邮件通知测试QA 和测试环境邮件拦截。不适合使用 Mailpit 的场景Mailpit 不应被当作正式邮件投递服务企业邮件系统邮件营销平台邮件信誉管理平台SPF、DKIM 和 DMARC 完整投递测试平台大规模生产邮件队列。Mailpit 可以验证“应用生成了怎样的邮件”但不能完全证明这封邮件进入真实互联网后一定能够成功投递。真实投递还受到以下因素影响发件域名信誉SPFDKIMDMARCIP 信誉邮件服务商反垃圾策略发送频率退信率用户投诉率。因此更完整的邮件测试体系通常分为三层第一层单元测试 验证模板生成和业务逻辑 第二层Mailpit 集成测试 验证 SMTP 发送、收件人、主题、正文和附件 第三层真实邮箱冒烟测试 验证真实邮件服务商的最终投递结果推荐的项目实践一个相对稳健的环境配置是环境邮件处理方式Local全部发送到 MailpitCI启动临时 Mailpit 容器并通过 API 断言Test使用带认证的共享 MailpitStaging默认捕获少量邮件经人工确认后 RelayProduction连接正式邮件服务商同时建议使用环境变量切换 SMTP 配置禁止本地环境连接生产 SMTP在 CI 中清理历史邮件使用唯一测试邮箱避免并发测试相互影响使用轮询等待邮件不使用固定 Sleep对收件人、主题、正文、链接和附件分别断言测试临时错误、永久错误和重复发送将 Mailpit 端口限制在开发网络内部对共享测试实例启用认证对邮件模板建立快照或视觉回归测试。总结Mailpit 本质上是在应用和真实邮件服务之间建立了一个可观察、可控制的测试边界。它让开发者可以保留真实 SMTP 发送流程避免测试邮件误发在浏览器中检查 HTML、文本、Header 和附件使用 REST API 编写自动化测试使用 Chaos 模拟 SMTP 异常在确认邮件内容后选择性地 Relay将邮件测试集成到 Docker、CI 和端到端测试中。对于需要开发注册、密码重置、订单通知和告警邮件的项目Mailpit 不应只是一个临时调试工具而可以成为邮件质量门禁的一部分生成邮件 ↓ 捕获邮件 ↓ 内容断言 ↓ 链接检查 ↓ 兼容性检查 ↓ 异常恢复测试 ↓ 允许进入真实投递流程如果项目仍然通过日志打印邮件正文或者由开发人员反复向自己的真实邮箱发送测试邮件引入 Mailpit 通常可以显著提升邮件开发的安全性、可观察性和自动化程度。
![[C++]内存管理：串顺序存储的内存回收](http://pic.xiahunao.cn/yaotu/[C++]内存管理：串顺序存储的内存回收)
