发送事务邮件

完成后,验证邮件、密码重置邮件和你自己的产品邮件会用可编辑的模板,通过 Resend、Cloudflare Email Service 或阿里云邮件推送发出。

邮件使用模板,通过当前启用的一个服务商发送。每次尝试,无论是否发出,都会写入投递日志。请在上线前配置好。没有服务商时,用户收不到验证邮件和密码重置邮件。

准备工作

  • 一个已在服务商完成验证的发信域名(需添加 SPF、DKIM 等 DNS 记录)。未验证域名发出的邮件会被拒绝。
  • 服务商的凭据。
  • 拥有 config.read 和 config.write 的管理员账号。

按你的域名和账号所在平台选择服务商:

服务商凭据发件人
Resend一个 API key发件人地址,需属于在 Resend 验证过的域名
Cloudflare EmailAccount ID 和 API token发件人地址,需属于在 Cloudflare 开通 Email Service 的域名
Aliyun DirectMailAccessKey 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。

src/server/services/example.service.ts
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。

参考

下一步