发送事务邮件
完成后,验证邮件、密码重置邮件和你自己的产品邮件会用可编辑的模板,通过 Resend、Cloudflare Email Service 或阿里云邮件推送发出。
邮件使用模板,通过当前启用的一个服务商发送。每次尝试,无论是否发出,都会写入投递日志。请在上线前配置好。没有服务商时,用户收不到验证邮件和密码重置邮件。
准备工作
- 一个已在服务商完成验证的发信域名(需添加 SPF、DKIM 等 DNS 记录)。未验证域名发出的邮件会被拒绝。
- 服务商的凭据。
- 拥有
config.read和config.write的管理员账号。
按你的域名和账号所在平台选择服务商:
| 服务商 | 凭据 | 发件人 |
|---|---|---|
| Resend | 一个 API key | 发件人地址,需属于在 Resend 验证过的域名 |
| Cloudflare Email | Account ID 和 API token | 发件人地址,需属于在 Cloudflare 开通 Email Service 的域名 |
| Aliyun DirectMail | AccessKey ID 和 Secret | 在邮件推送控制台创建的 发信地址;不使用 发件人地址 |
在邮件服务商完成准备
| 厂商 | 适用场景 |
|---|---|
| Resend | 通过已验证域名和发信密钥发信 |
| Cloudflare Email | 使用 Cloudflare 账户和发信令牌 |
| 阿里云邮件推送 | 通过指定地域的发信地址发信 |
接入服务商
打开邮件配置
进入 设置 → 邮件配置(/admin/config/email)。顶部卡片分别是 Resend、Cloudflare Email 和 Aliyun DirectMail。凭据已保存的卡片显示 已配置,否则显示 缺少配置。当前负责发信的服务商带有 启用中 标记。点击要配置的卡片。
设置发件人
在 投递设置 中填写 发件人地址(Resend 和 Cloudflare 使用),例如 Acme <noreply@mail.example.com>;以及 联系表单通知收件人,即接收 /contact 表单内容的邮箱。留空的字段会保留当前值。
启用并保存
勾选 设为当前邮件 provider,点击 保存 provider。卡片显示 启用中,运行状态 面板显示当前服务商和发件人。
保存的效果取决于这个复选框。勾选时,该卡片的服务商成为当前启用的服务商。在当前启用服务商的卡片上取消勾选,会关闭邮件发送。在其他卡片上不勾选,只保存该服务商的配置。复选框下方一行显示 当前启用:… 或 邮件发送已关闭:没有启用的 provider。
尚未配置服务商时
不会发出任何邮件,每次尝试都记录为 not_configured。注册仍然可以完成,但如果开启了 邮箱验证,未验证邮箱的用户将无法登录。在服务商启用之前,/setup 会把 邮件投递 列为必需项。
了解自动发送的邮件
以下模板无需你写代码就会发送:
| 模板 | 触发时机 |
|---|---|
email-verification | 注册时;要求邮箱验证期间未验证用户尝试登录时;用户请求重发时。 |
password-reset | 用户申请重置密码时。固定使用英文。 |
contact-routed | 有人提交联系表单时,发到 联系表单通知收件人。 |
模板集合中还有 registration-success、newsletter-welcome、billing-receipt、payment-success、subscription-renewal、subscription-canceled、payment-failed、invoice-ready 和 security-alert。它们不会自动发送,需要在你自己的代码中发送。
编辑模板
打开模板
打开 /admin/email/templates(属于 设置 分组中的 邮件 区域)。每个模板按语言各出现一次,位于 模板配置 下,key 下方列出其变量。
修改内容
修改主题、文本正文 或 HTML 正文。变量使用 {{name}} 占位符,发送时变量值会经过 HTML 转义。
保存并预览
点击 保存模板,看到 模板已保存。 即完成,变量列表会根据占位符重新生成。然后打开 /admin/email/preview,选择模板并点击 渲染预览。预览与正式投递使用同一套布局。
在代码中发送邮件
用模板 key、收件人、语言和模板变量调用邮件 service。
import { sendEmailTest } from "@/server/services/email-notifications.service";
const delivery = await sendEmailTest({
templateKey: "payment-success",
to: user.email,
locale: "zh",
variables: {
name: user.name,
planName: "Pro",
amount: "¥199.00",
orderId: order.id,
receiptUrl: receiptUrl,
},
});
if (delivery.status !== "sent") {
console.warn("Email not sent", delivery.status, delivery.errorMessage);
}调用返回投递日志记录,状态为 sent、failed 或 not_configured。只有模板不存在时才抛出错误。缺少模板用到的任一变量时不会发送,记录为 failed,错误为 Missing template variables: ...。
验证
发送测试邮件
打开 /admin/email/test,页头显示 Provider 已就绪。选择 模板 和 语言,在 收件人 中填写自己的邮箱,在 变量 JSON 中为每个变量填值,点击 发送测试邮件。表单显示 邮件投递已记录: 及结果。
检查投递
邮件到达收件箱,/admin/email/deliveries 中这条记录状态为 sent;在 /auth/forgot-password 为已有账号申请重置密码,能收到重置链接。
pnpm validate:email 会检查模板、预览、投递日志和服务商接线。EXTERNAL_VALIDATE_EMAIL_TO=you@example.com pnpm validate:external 会真实发送一封密码重置邮件。
常见问题
投递状态为 not_configured
当前服务商缺少凭据,或邮件发送已关闭。Resend 需要 API Key;Cloudflare 需要 Account ID 和 API Token;阿里云需要 AccessKey ID、Secret 和发信地址。
保存服务商卡片后邮件停止发送
当前启用服务商的卡片在 设为当前邮件 provider 未勾选时被保存。打开该卡片,勾选后点击 保存 provider。
投递 failed,错误与发件人或域名有关
服务商拒绝了发件人。在服务商处完成域名验证,并确认 发件人地址(或阿里云的 发信地址)属于该域名。
报错 "Email template not found"
该 key 和语言下没有模板。新数据库请运行 pnpm db:seed-baseline。