email

添加邮件功能

帮用户为项目集成邮件发送能力。

步骤

1. 了解需求

问题 1：邮件用途

你需要发什么邮件？

• 注册验证邮件
• 密码重置邮件
• 通知邮件（订单确认、状态更新）
• 营销邮件（推广、新闻通讯） 可以多选。

2. 选择邮件服务

推荐方案：

• Resend（最简单，API 友好，免费额度 3000 封/月）
• SendGrid（功能全面，免费 100 封/天）
• AWS SES（价格最低，适合大批量发送，但配置复杂）
• Nodemailer + Gmail（仅限开发测试，不推荐生产） 不确定就用 Resend。

3. 域名验证（关键步骤，直接影响送达率）

在邮件服务商后台获取 DNS 记录，然后到域名 DNS 管理面板添加以下三项：

• SPF — TXT 记录，声明哪些服务器有权代你发邮件。示例值：v=spf1 include:_spf.resend.com ~all
• DKIM — TXT 或 CNAME 记录，用公钥签名验证邮件未被篡改。服务商会提供具体值
• DMARC — TXT 记录，告诉收件服务器如何处理验证失败的邮件。最低配置：v=DMARC1; p=none; rua=mailto:你的邮箱

三项全部配置后，等待 DNS 生效（通常 5-30 分钟），然后在服务商后台点击"验证域名"。

4. 生成邮件代码

• 邮件发送工具 — 封装发送函数，支持 HTML 和纯文本
• 邮件模板 — 根据用途生成 HTML 邮件模板（简洁专业的样式），包含：品牌 Logo 位置、正文区域、行动按钮（如"验证邮箱"）、底部退订链接（营销邮件必须有）
• 环境变量 — API Key 配置，添加到 .env.example
• 发送频率控制 — 加入基本限速逻辑（如每秒最多 2 封），避免触发服务商速率限制或被标记为垃圾邮件发送者。批量发送（超过 50 封）必须用队列异步处理

5. 测试

发送测试邮件到至少两个不同邮箱提供商（如 Gmail + Outlook），逐项检查：

• 邮件是否到达收件箱（不是垃圾箱）
• HTML 模板在不同客户端的显示是否正常
• 退订链接是否可点击
• 发件人名称和地址是否正确

邮件功能已配置。测试邮件发送成功，收件箱送达正常。

遇到问题

• 邮件进了垃圾箱 — 检查 SPF/DKIM/DMARC 是否全部配置且验证通过。用 mail-tester.com 发一封测试邮件打分，7 分以下说明有配置问题。新域名建议前两周低量发送，逐步建立信誉
• API Key 报错或 401 — 确认 .env 中的 Key 是从服务商后台复制的完整值（无多余空格）。区分测试 Key 和生产 Key：测试 Key 只能发到验证过的邮箱
• 模板渲染异常 — 邮件 HTML 兼容性差，避免使用 flexbox/grid 布局，用 table 布局。用 Litmus 或 Email on Acid 预览不同客户端的渲染效果
• 发送成功但对方没收到 — 检查服务商后台的发送日志，看是否被对方服务器拒收（bounce）。常见原因：收件地址不存在、对方服务器屏蔽了你的域名