mailtrap-email-integration

Mailtrap Email Integration 是一套指导性模式，用于在应用中通过 Mailtrap 的 Email API 与 Sandbox 添加事务性邮件发送能力，内容覆盖认证方式、环境隔离，以及常见的投递陷阱。

用途与激活时机

该技能适用于以下情形：实现“发送邮件”功能，例如注册确认、密码重置、通知、收据；排查开发或预发环境中邮件为何未送达；为项目搭建首次邮件发送集成；审查那些直接调用邮件 API、却未做沙箱隔离的代码。

核心概念

沙箱与生产分离：Mailtrap 提供 Sandbox API，会捕获邮件而不实际投递，用于开发和预发环境，确保测试邮件不会进入真实收件箱。生产发送使用另一个经过验证域名的端点。绝不能把开发环境指向生产发送端点。

认证：请求在 Authorization 头中使用 Bearer Token。Token 按项目划分作用域；沙箱与生产通常使用不同的 Token。

域名验证：生产发送需要通过 DNS 记录（SPF、DKIM、DMARC）验证发信域名，Mailtrap 才会向真实收件人投递。跳过此步骤会导致静默投递失败或邮件落入垃圾邮件文件夹。

代码示例

生产环境通过 Mailtrap Email API 发送：

async function sendEmail(to: string, subject: string, html: string) { const response = await fetch("https://send.api.mailtrap.io/api/send", { method: "POST", headers: { "Authorization": Bearer ${process.env.MAILTRAP_API_TOKEN}, "Content-Type": "application/json", }, body: JSON.stringify({ from: { email: "no-reply@yourverifieddomain.com", name: "Your App" }, to: [{ email: to }], subject, html, }), });

if (!response.ok) { throw new Error(Email send failed: ${response.status}); } return response.json(); }

非生产环境将同一调用路由到 Sandbox：

const MAILTRAP_ENDPOINT = process.env.NODE_ENV === "production" ? "https://send.api.mailtrap.io/api/send" : https://sandbox.api.mailtrap.io/api/send/${process.env.MAILTRAP_INBOX_ID};

反模式

在开发/测试中使用生产发送端点：真实测试邮件会进入真实收件箱，可能引发垃圾邮件投诉并泄露测试数据；应改为将非生产环境路由到 Sandbox 端点。

在源码中硬编码 API Token：提交到版本控制后存在凭据泄露风险；应从环境变量或密钥管理器中加载 Token。

在域名验证完成前发送：邮件会静默失败或进入垃圾邮件；应在启用生产发送前验证 SPF/DKIM/DMARC 记录。

发送失败时没有重试或错误处理：会造成通知静默失败，例如用户始终收不到密码重置邮件；应检查响应状态、记录失败并暴露可操作的错误信息。

最佳实践

将沙箱与生产 Token 放在各自独立的环境变量中，绝不在环境之间共用一个 Token。在任何涉及邮件的生产上线之前，验证发信域名的 DNS 记录。记录投递失败时保留足够上下文以便排查，包括收件人、模板、时间戳与响应码。把发送邮件视为可能失败的网络调用：用 try/catch 包裹，绝不假设一定成功。

技能介绍