邮件总览
事务邮件的用途、两个地址的区别与 provider 选择
最近更新 2026 年 11 月 3 日
邮件模块给站点的三处提供发信能力：邮箱验证与欢迎信、联系表单转发的消息、管理端手动发信。 发信渠道二选一：Resend 或 Cloudflare Email，接入步骤各写一页。
要决定的三件事
| 决定 | 在哪配 | 作用 |
|---|---|---|
| 发件地址 | MAIL_FROM | 验证邮件、重置密码、欢迎信的发件人 |
| 支持邮箱 | mail.supportEmail | 联系表单的收件人，也是页脚 mailto: 入口 |
| 开关 | mail.enabled | 关掉后邮件相关的 API 一律返回 404 MODULE_DISABLED |
前两项互相独立：配了其中一个不会自动填另一个，地址也可以分别选。MAIL_FROM 必须是纯邮箱 地址（noreply@<your-domain.com>），不接受 Brand <noreply@...> 这种带显示名的写法。
选 provider
| provider | 必要配置 | 接入页面 |
|---|---|---|
resend | RESEND_API_KEY + MAIL_FROM | Resend |
cloudflare | MAIL_FROM（或 CLOUDFLARE_EMAIL_SENDER）+ EMAIL binding | Cloudflare Email |
开了之后有什么
- 认证邮件：
auth.requireEmailVerification为true（默认）时，注册发验证邮件、验证成功后发
欢迎邮件、忘记密码发重置链接。邮件没配齐时 auth 会被判为配置矛盾，/api/auth/* 返回 503， 不会自动降级成免验证登录。
- 联系表单：
contact.enabled为true时，表单消息发到mail.supportEmail。它依赖邮件模块
配置完整——邮件不通时 /api/contact 返回 503，不会让访客以为已送达。
- 手动发信：
/api/email供管理端发模板邮件，要求已登录且收件人在ADMIN_EMAILS白名单内。
验证
pnpm run check:env 按当前开启的模块列出缺失配置，邮件相关诊断出现在 mail 一项下。
bash
pnpm email:dev在 3001 端口预览模板（src/mail/templates/），改模板即时热更新。
注意事项
- 同一时刻只有一个 provider 生效，由
mail.provider决定走哪条链路。 - 缺密钥或缺发件地址时该 provider 不会注册，调用会明确失败，不会用占位地址把邮件发出去。
- 邮件主题与正文按访客语言渲染，新增模板要同时补中文与英文。
配好后可以接着做 邮件订阅——同一套发信凭据也能用来收订阅名单。