api-email-setup-resend

Resend Email と React Email のセットアップ

クイックガイド： React Email テンプレートで Resend のメール API を使用します。react プロパティを使ってコンポーネントを直接 resend.emails.send() に渡せば、手動で render() を実行する必要はありません。モノレポ内で分離できるよう、メールテンプレートは専用のパッケージに配置します。本番環境で使用する前に、送信ドメインを検証してください。HTML 文字列への手動レンダリングが必要な場合は、@react-email/components ではなく @react-email/render を使用します。

---

<critical_requirements>

重要：このスキルを使用する前に

すべてのコードは、CLAUDE.md のプロジェクト規約に従う必要があります（ケバブケース、名前付きエクスポート、インポートの順序、import type、名前付き定数）

（RESEND_API_KEY 環境変数を必ず使用してください。API キーをハードコードしてはいけません）

（本番環境で使用する前に、Resend ダッシュボードで送信ドメインを必ず検証してください。未検証のドメインでは、自分のメールアドレスにしか送信できません）

（メール UI コンポーネントには @react-email/components を、HTML レンダリングには @react-email/render を必ず使用してください。これらは別々のパッケージです）

（基本の送信方法として、必ず resend.emails.send({ react: MyTemplate(props) }) を使用してください。手動で render() を実行して HTML にするのは、Resend 以外の送信サービスを使用する場合に限ります）

</critical_requirements>

---

自動検出： Resend のセットアップ、Resend のインストール、React Email のセットアップ、メールテンプレートのセットアップ、RESEND_API_KEY、ドメイン検証、SPF DKIM DMARC、トランザクションメールのセットアップ、メールプレビューサーバー、@react-email/components、react-email

使用する場面：

• プロジェクトで Resend と React Email を初めてセットアップするとき
• ドメイン検証と DNS レコードを設定するとき
• メールプレビュー用の開発サーバーをセットアップするとき
• モノレポでメールテンプレートを構成するとき

使用しない場面：

• マーケティングメールキャンペーン（専用のマーケティングメールプラットフォームを使用してください）
• 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. モノレポ内で分離 - メールテンプレートはアプリケーションコードに混在させず、専用のパッケージに配置します
4. render() より react プロパティを優先 - Resend SDK は、react プロパティ経由でコンポーネントを渡すと、内部でレンダリングします

---

基本パターン

パターン 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/components ではなく @react-email/render を指定してください。

送信とレンダリングの詳細な例については、examples/core.md を参照してください。

---

パターン 2：ドメイン検証

カスタムアドレスから送信するには、ドメインを検証してください。未検証のアカウントでは、自分のメールアドレスにしか送信できません。

1. Resend ダッシュボードで［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：モノレポのパッケージ構成

メールテンプレートはアプリケーションコードとは分け、専用パッケージに保存してください。

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.json() ではなく、必ず request.text() を使用してください。検証前に JSON としてパースすると、暗号署名が破損します。verify() メソッドは失敗時に例外をスローします（{ data, error } を返す emails.send() とは異なります）。

---

<red_flags>

要注意事項

優先度：高

• ソースコードに RESEND_API_KEY をハードコードする（セキュリティ上の脆弱性となり、Git 上で見える状態になります）
• 本番環境で未検証のドメインから送信する（メールの送信に失敗するか、迷惑メールとして扱われます）
• @react-email/components から render をインポートする（パッケージが間違っています。@react-email/render を使用してください）
• render() の使用時に await しない（Promise が返され、メール本文が [object Promise] になります）

優先度：中

• resend.emails.send() のエラー処理がない（失敗が通知されません）
• 専用パッケージではなくアプリのディレクトリ内にメールテンプレートを置く（モノレポでバンドルの問題が発生します）
• Webhook ペイロードに request.text() ではなく request.json() を使用する（署名検証が機能しません）

注意点とエッジケース：

• Resend の無料プランでは、1 日あたり 100 通、1 か月あたり 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 ダッシュボードで送信ドメインを必ず検証してください。未検証のドメインからは自分のメールアドレスにしか送信できません）

（メールの UI コンポーネントには @react-email/components、HTML のレンダリングには @react-email/render を必ず使用してください。これらは別々のパッケージです）

（送信方法には resend.emails.send({ react: MyTemplate(props) }) を必ず使用してください。HTML への手動 render() は、Resend 以外の送信元を使用する場合にのみ必要です）

これらのルールに従わないと、メールの配信に失敗したり、セキュリティ上の脆弱性が生じたりする可能性があります。

</critical_reminders>