api-email-setup-resend

Resend 邮件与 React Email 设置

**快速指南：**使用 Resend 邮件 API 和 React Email 模板。通过 react 属性直接将组件传递给 resend.emails.send()，无需手动调用 render()。将邮件模板放在专用包中，以便在 monorepo 中隔离。上线前请验证发件域名。如果需要手动将内容渲染为 HTML 字符串，请使用 @react-email/render（而非 @react-email/components）。

---

<critical_requirements>

关键要求：使用此技能前

所有代码都必须遵循项目在 CLAUDE.md 中的约定（kebab-case、命名导出、导入排序、import type、命名常量）

（必须使用 RESEND_API_KEY 环境变量——绝不能将 API 密钥硬编码）

（上线前必须在 Resend 控制面板中验证发件域名——未验证的域名只能向你自己的邮箱发送邮件）

（必须使用 @react-email/components 构建邮件 UI 组件，并使用 @react-email/render 渲染 HTML——这是两个不同的包）

（主要发送方式必须使用 resend.emails.send({ react: MyTemplate(props) })——仅在使用非 Resend 发送服务时，才需要手动调用 render() 将内容渲染为 HTML）

</critical_requirements>

---

**自动检测：**Resend 设置、Resend 安装、React Email 设置、邮件模板设置、RESEND_API_KEY、域名验证、SPF DKIM DMARC、事务性邮件设置、邮件预览服务器、@react-email/components、react-email

适用场景：

• 在项目中初始设置 Resend 和 React Email
• 配置域名验证和 DNS 记录
• 设置邮件预览开发服务器
• 在 monorepo 中组织邮件模板

不适用场景：

• 营销邮件活动（请使用专用的营销邮件平台）
• SMS 或推送通知（需要使用其他服务）
• 非 JavaScript 后端（此技能涵盖 React Email 模板，需要 Node.js）
• 需要 SMTP 中继（Resend 仅提供 API）

详细资源：

• examples/core.md - 客户端设置、发送方式、模板结构、预览服务器

---

理念

Resend 是由 React Email 的创建者打造的开发者优先型邮件 API。React Email 将现代组件模式引入邮件开发，取代传统的基于表格的 HTML。

核心原则：

1. 将邮件作为 React 组件——使用 JSX、Tailwind CSS 和 TypeScript 编写邮件
2. 发送前先预览——本地开发服务器可显示邮件的实际渲染效果
3. 在 monorepo 中隔离——将邮件模板放在专用包中，不与应用代码混在一起
4. 优先使用 react 属性，而非 render()——通过 react 属性传入组件时，Resend SDK 会在内部完成渲染

---

核心模式

模式 1：使用 react 属性发送（首选）

Resend SDK 支持通过 react 属性直接接收 React 组件，无需手动渲染 HTML。

const { data, error } = await resend.emails.send({
  from: "Your App <[email protected]>",
  to: ["[email protected]"],
  subject: "Welcome!",
  react: WelcomeEmail({ userName: "John" }),
});

**优点：**无需手动调用 render()，SDK 会在内部处理转换，代码更简洁

**何时改用 render()：**仅在通过需要 HTML 字符串的非 Resend 邮件服务发送时使用。从 @react-email/render 导入，而非 @react-email/components。

完整的发送与渲染示例请参阅 examples/core.md。

---

模式 2：域名验证

验证域名后，才能使用自定义地址发送邮件。未验证的账户只能向你自己的邮箱发送邮件。

1. 前往 Resend Dashboard > Domains > Add Domain
2. 将 Resend 提供的 DNS 记录添加到你的 DNS 服务商：
   • SPF（TXT）：v=spf1 include:amazonses.com ~all
   • DKIM（3 条 CNAME 记录）：Resend 提供的值
   • DMARC（TXT，建议配置）：v=DMARC1; p=none; rua=mailto:[email protected]
3. 点击 Verify——DNS 传播最多可能需要 48 小时

**重要原因：**未验证的域名只能向账户邮箱发送邮件。生产环境发送邮件必须完成验证。正确的 DNS 记录有助于避免邮件被归入垃圾邮件。

---

模式 3：Monorepo 包结构

将电子邮件模板保存在专用包中，与应用代码分开。

packages/emails/
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts              # Re-export all templates
│   ├── client.ts             # Resend client singleton
│   ├── layouts/
│   │   └── base-layout.tsx   # Shared layout wrapper
│   ├── components/
│   │   ├── button.tsx        # Reusable email button
│   │   └── footer.tsx        # Email footer
│   └── templates/
│       ├── verification-email.tsx
│       ├── password-reset.tsx
│       └── welcome-email.tsx
└── emails/                   # For react-email dev server

优点： 可在多个应用间复用，避免打包问题，清晰划分关注点

完整的客户端设置和模板示例，请参阅 examples/core.md。

---

模式 4：电子邮件错误处理

Resend 会返回 { data, error }——务必检查错误。

const { data, error } = await resend.emails.send(emailOptions);

if (error) {
  console.error("[Email] Send failed:", error.name, error.message);
  return { success: false, error: error.message };
}

return { success: true, id: data?.id };

优点： 显式检查错误、结构化日志记录，并返回类型化结果。切勿忽略错误响应——SDK 在发送失败时不会抛出异常。

---

模式 5：Webhook 验证

处理事件前，务必验证 Webhook 签名。verify() 方法在签名无效时会抛出异常。

const payload = await request.text(); // Raw body, NOT parsed JSON

try {
  const event = resend.webhooks.verify({
    payload,
    headers: {
      id: request.headers.get("svix-id") ?? "",
      timestamp: request.headers.get("svix-timestamp") ?? "",
      signature: request.headers.get("svix-signature") ?? "",
    },
    webhookSecret: process.env.RESEND_WEBHOOK_SECRET!,
  });

  // event.type: "email.sent" | "email.delivered" | "email.bounced" | etc.
} catch {
  return new Response("Invalid webhook signature", { status: 400 });
}

优点： 使用 SDK 内置验证，使用原始请求体（而非会导致签名失效的已解析 JSON），通过 try/catch 处理无效签名

注意事项： 必须使用 request.text()，而不是 request.json()——验证前将请求体解析为 JSON 会破坏加密签名。verify() 方法在失败时会抛出异常（不同于返回 { data, error } 的 emails.send()）。

---

<red_flags>

风险信号

高优先级：

• 在源代码中硬编码 RESEND_API_KEY（安全漏洞，会暴露在 git 中）
• 在生产环境中使用未经验证的域名发送邮件（邮件会发送失败或被判定为垃圾邮件）
• 从 @react-email/components 导入 render（包不正确——应使用 @react-email/render）
• 使用 render() 时没有等待其完成（它会返回 Promise，邮件正文会变成 [object Promise]）

中优先级：

• 对 resend.emails.send() 不做错误处理（失败时不会有提示）
• 将电子邮件模板放在应用目录中，而不是专用包中（会导致 monorepo 打包问题）
• 在 Webhook 负载中使用 request.json() 而不是 request.text()（会破坏签名验证）

注意事项与边缘情况：

• Resend 免费套餐：每天 100 封邮件，每月 3000 封邮件
• 未验证的域名只能向账户邮箱地址发送邮件
• 域名验证的 DNS 传播最多需要 48 小时
• React Email 开发服务器会在项目中创建 .react-email 文件夹
• 在电子邮件模板中使用 Grid、Flexbox 或 box-shadow 在 Gmail/Outlook 中不起作用
• 在电子邮件中使用 px 单位——rem 在不同邮件客户端中的呈现不一致
• 在 Resend SDK v6.1.0+ 中，某些打包器可能会因 @react-email/render 报错——如果遇到解析错误，请将 resend 添加到打包器的外部包配置中
• @react-email/components 用于 UI 组件（Body、Button 等）；@react-email/render 用于 render() 工具函数——它们是不同的包

</red_flags>

---

<critical_reminders>

重要提醒

（必须使用 RESEND_API_KEY 环境变量——绝不要硬编码 API 密钥）

（生产环境使用前，必须在 Resend 控制面板中验证发件域名——未经验证的域名只能向你自己的邮箱发送邮件）

（必须使用 @react-email/components 提供电子邮件 UI 组件，并使用 @react-email/render 渲染 HTML——它们是不同的包）

（必须将 resend.emails.send({ react: MyTemplate(props) }) 作为主要发送方式——只有使用非 Resend 发件服务时，才需要手动调用 render() 生成 HTML）

不遵守这些规则会导致邮件发送失败或引发安全漏洞。

</critical_reminders>