第三方集成

Resend 集成

配置 Resend 以支持魔法链接登录、邮件营销与生命周期工作流。

Resend 是面向开发者的事务邮件 API，负责发送、追踪与管理邮件，让你专注业务而无需自建 SMTP 基础设施。TanStack Ship 通过 Resend 实现以下能力：

  • 魔法链接登录 — 用户输入邮箱后收到一次性登录链接（src/lib/auth.ts）
  • 邮件营销活动 — 管理端创建 HTML 活动，经 Cloudflare Queues 异步投递（email-campaign-queue）
  • 生命周期工作流 — 自动化序列邮件（workflow-queue）

重要

推送代码到 GitHub 不会更新生产环境密钥。RESEND_API_KEY 需通过 .dev.vars（本地）或 wrangler secret put（生产）配置。

注册与 API Key

  1. 访问 resend.com 注册账号
  2. 进入 API Keys → Create API Key
  3. 复制以 re_ 开头的密钥
  4. 写入本地 .dev.vars：
bash
RESEND_API_KEY=re_xxxxxxxx
  1. 生产环境执行：
bash
pnpm wrangler secret put RESEND_API_KEY

须知

API Key 等同于发信凭证，不要提交到 Git 或暴露在客户端代码中。泄露后立即在 Resend 控制台撤销并轮换。

配置发信地址 EMAIL_FROM

EMAIL_FROM 决定收件人看到的发件人名称与地址，格式示例：

bash
EMAIL_FROM="TanStack Ship <no-reply@your-domain.com>"
要求说明
域名验证@ 后的域名必须在 Resend Domains 中显示 Verified
显示名称引号包裹时可包含空格，如 "My App <no-reply@example.com>"
生产存放非敏感，可放 wrangler.jsonc → vars，或作为 secret

域名与 DNS 验证

添加域名

  1. Resend Dashboard → Domains → Add Domain
  2. 输入发信根域（如 your-domain.com）
  3. 按页面提示添加 DNS 记录（通常含 SPF、DKIM 等）
  4. 若 DNS 托管在 Cloudflare，可尝试 Sign in to Cloudflare 一键导入前三条记录
  5. _dmarc 记录需在 Cloudflare DNS 页面手动添加
  6. 全部通过后 Status 为 Verified

须知

若长时间未通过验证，在 Domains 页点击 Restart 重新检测。邮件相关 DNS 记录建议设为 DNS only（灰云），避免代理影响验证。

DMARC 分阶段策略

阶段记录值用途
初期监控v=DMARC1; p=none; rua=mailto:dmarc@your-domain.com; pct=100仅收集报告，不影响投递
中期隔离v=DMARC1; p=quarantine; rua=mailto:dmarc@your-domain.com; pct=100失败邮件进垃圾箱
最终拒绝v=DMARC1; p=reject; rua=mailto:dmarc@your-domain.com; pct=100拒绝未通过验证的邮件，防域名伪造

将 rua 替换为你接收聚合报告的真实邮箱。

代码中的用法

魔法链接在认证流程中同步调用 Resend API：

typescript
// src/lib/auth.ts
const resend = new Resend(requireEnv('RESEND_API_KEY'))
await resend.emails.send({
  from: requireEnv('EMAIL_FROM'),
  to: input.email,
  subject: 'Your sign-in link',
  html: `<p><a href="${url}">Sign in</a></p>`,
})

批量营销邮件在 Queue Consumer 中调用，参见 src/server/email-campaign-queue.ts。

须知

TanStack Ship 未使用 RESEND_SEGMENT_ID。联系人可在 Resend Audiences 中管理，或使用 Dashboard 的 Broadcast 发送营销邮件。

环境变量汇总

变量敏感本地生产
RESEND_API_KEY✓.dev.varswrangler secret
EMAIL_FROM.dev.varswrangler.jsonc vars

完整变量表见 环境变量 页。

验证清单

完成配置后逐项确认：

  1. 登录页输入邮箱，触发魔法链接
  2. Resend → Emails 查看发送状态为 Delivered
  3. Resend → Logs 有对应 API 请求
  4. 收件箱收到邮件，链接可完成登录
  5. （可选）管理端 /dashboard/admin/... 创建测试邮件活动，确认 Queue 消费成功

警告

若本地能发、生产不能发，检查 wrangler secret list 是否包含 RESEND_API_KEY，以及 EMAIL_FROM 域名在生产环境同样已 Verified。

相关文档