Cloudflare Email Sending 集成

Cloudflare Email Sending 是 Cloudflare 提供的邮件发送服务，适合已经使用 Cloudflare 托管域名的项目。与 Resend 相比，它不需要额外注册第三方邮件服务商，并且可以与 Cloudflare 的域名、DNS 管理无缝衔接。

在 NEXTY.DEV 模板中，邮件发送已经抽象为统一的 lib/mail 入口。你可以通过环境变量在 Resend 和 Cloudflare Email Sending 之间切换，业务代码无需改动。

前置条件

一个 Cloudflare 账号，并且你的域名已经托管在 Cloudflare 上。
如果你使用 Cloudflare Workers 部署，请参考 cf-pg 分支的邮件绑定方式。本文档针对服务器部署或 Vercel 部署，使用 Cloudflare SDK 的 REST API 发送邮件。

配置域名

点击开始绑定域名，按页面提示选择你要使用的域名。

域名添加成功后，点击域名进入详情页，再点击 Connect 完成连接。

连接完成后，Cloudflare 会提示你需要添加的 DNS 记录（例如 SPF、DKIM、DMARC 等）。按照控制台指引在对应域名的 DNS 页面添加这些记录，直到邮件发送状态显示为可用。

创建 API Token

为了让调用 Cloudflare Email Sending REST API 发送邮件，你需要创建一个专用 API Token。

打开 Cloudflare API Tokens 页面，点击 Create Token。
选择 Create Custom Token。

按以下规则填写：
- Token name：自定义，例如 nexty-email-sending。
- Permissions：
  - Account → Email Sending → Edit
  - Zone → Email Routing Rules → Edit
- Account Resources：
  - Include → 选择当前账号
- Zone Resources：
  - Include → Specific zone → 选择当前域名

复制生成的 Token。
在 Cloudflare 控制台右侧找到 Account ID 并复制。

配置环境变量

将上一步获取的信息填入环境变量：

# 邮件服务商：resend 或 cloudflare，默认 resend
DEFAULT_EMAIL_PROVIDER=cloudflare
 
# 发件人信息，Resend 和 Cloudflare 共用
DEFAULT_ADMIN_EMAIL=[email protected]
DEFAULT_ADMIN_NAME="Your App Name"
 
# Cloudflare Email Sending 专用
CLOUDFLARE_EMAIL_API_TOKEN=your_api_token
CLOUDFLARE_ACCOUNT_ID=your_account_id

DEFAULT_EMAIL_PROVIDER：可选 resend 或 cloudflare，用于控制 lib/mail 的默认服务商。
DEFAULT_ADMIN_EMAIL：发件人邮箱，必须是已经通过 Cloudflare Email Sending 验证的域名邮箱。
DEFAULT_ADMIN_NAME：发件人显示名称。
CLOUDFLARE_EMAIL_API_TOKEN：上一步创建的 API Token。
CLOUDFLARE_ACCOUNT_ID：Cloudflare 账号 ID。

在代码中发送邮件

业务代码统一通过 lib/mail 的 sendEmail 发送邮件，无需关心底层是 Resend 还是 Cloudflare。

import { sendEmail } from "@/lib/mail";
import { NewsletterWelcomeEmail } from "@/emails/newsletter-welcome";
 
const result = await sendEmail({
  to: "[email protected]",
  from: {
    email: process.env.DEFAULT_ADMIN_EMAIL!,
    name: process.env.DEFAULT_ADMIN_NAME || "Your App Name",
  },
  subject: "Welcome to our service!",
  react: NewsletterWelcomeEmail,
  reactProps: {
    email: "[email protected]",
    unsubscribeLink: "https://yourdomain.com/unsubscribe?token=xxx",
  },
  headers: {
    "List-Unsubscribe": "<https://yourdomain.com/unsubscribe?token=xxx>",
  },
  addToContacts: true,
});
 
if (!result.success) {
  console.error("Send email failed:", result.error);
}

如果你需要显式指定服务商（例如 A/B 测试或同时向两个服务商发送），可以使用第二个参数：

import { sendEmail } from "@/lib/mail";
 
// 显式使用 Cloudflare
await sendEmail({ ...options }, "cloudflare");
 
// 显式使用 Resend
await sendEmail({ ...options }, "resend");

直接使用 Cloudflare SDK

如果你的产品需要绕过环境变量默认服务商，可以直接使用 Cloudflare SDK：

import Cloudflare from "cloudflare";
 
const client = new Cloudflare({
  apiToken: process.env.CLOUDFLARE_EMAIL_API_TOKEN,
});
 
const response = await client.emailSending.send({
  account_id: process.env.CLOUDFLARE_ACCOUNT_ID!,
  from: "[email protected]",
  to: "[email protected]",
  subject: "Welcome to our service!",
  html: "<h1>Welcome!</h1><p>Thanks for signing up.</p>",
  text: "Welcome! Thanks for signing up.",
});

推荐做法

统一使用 lib/mail 的 sendEmail，这样联系人管理、重试、React 模板渲染和文本 fallback 都由模板自动处理。

联系人管理说明

当默认服务商为 Resend 时，成功发送邮件后会把收件人同时加入 Resend Contacts 和 Redis 联系人集合。
当默认服务商为 Cloudflare 时，由于 Cloudflare Email Sending 目前不提供联系人 API，只会把收件人记录到 Redis 联系人集合。
退订逻辑（removeContact）会同时清理 Resend Contacts 和 Redis 记录，以保证切换服务商后退订仍然有效。

验证

配置完成后，可以通过以下方式验证：

在本地或预览环境正确设置上述环境变量。
访问网站 Footer 的邮件订阅输入框，输入一个测试邮箱并提交。
检查测试邮箱是否收到欢迎邮件。
登录 Cloudflare 控制台，进入 Email Sending 页面查看发送日志和状态。

注意事项

Cloudflare Email Sending 要求发件人域名必须已经通过 DNS 验证，否则邮件会被拒绝。
当前分支（main）的 Cloudflare 邮件实现基于 REST API，适用于 Node.js 服务器或 Vercel 部署。如果你使用 Cloudflare Workers 原生部署，请使用 cf-pg 分支，该分支通过 send_email binding 实现内部通信。
如果你同时配置了 Resend 和 Cloudflare 的环境变量，可以通过 DEFAULT_EMAIL_PROVIDER 随时切换，业务代码无需改动。