| name | email |
| description | 当用户想发邮件、加邮件验证、发通知邮件、集成 Resend/SendGrid 时使用 — 为项目添加邮件发送功能 |
添加邮件功能
帮用户为项目集成邮件发送能力。
步骤
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)。常见原因:收件地址不存在、对方服务器屏蔽了你的域名