/api-email-resend-react-email

name: api-email-resend-react-email
description: Resend + React Email templates

Email Patterns with Resend and React Email

> **Quick Guide:** Use Resend for transactional emails with React Email templates. Always `await render()` before sending (it returns a Promise). Server-side only - never expose API keys to clients. Implement retry with exponential backoff for transient failures. Include unsubscribe links in non-transactional emails (CAN-SPAM). Use `resend.batch.send()` for 2-100 recipients (no attachments or scheduling support in batch). React Email 5.0+ deprecated `renderAsync` - use `render()` instead. Webhook verification requires raw request body and `webhookSecret` parameter.

---

<critical_requirements>

CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST await `render()` before passing HTML to resend.emails.send() - render returns a Promise)**

**(You MUST handle Resend API errors and implement retry logic for transient failures)**

**(You MUST use server-side sending for all emails - never expose RESEND_API_KEY to the client)**

**(You MUST include unsubscribe links in marketing/notification emails - required for CAN-SPAM compliance)**

**(You MUST use typed props interfaces for all email templates - enables compile-time validation)**

</critical_requirements>

---

**Auto-detection:** Resend, React Email, @react-email/components, resend.emails.send, email template, transactional email, verification email, password reset email, notification email, email rendering, resend.batch.send, resend.webhooks.verify

**When to use:**

• Sending transactional emails (verification, password reset, receipts)
• Creating React Email templates with Tailwind styling
• Building notification systems with email delivery
• Implementing email tracking via webhooks
• Batch sending to multiple recipients

**When NOT to use:**

• Marketing campaign management (use dedicated marketing tools)
• SMS or push notifications (different services)
• Email list management (use Resend Audiences or marketing tools)

---

<philosophy>

Philosophy

Email in modern applications follows a **server-side, template-driven** approach. React Email brings component patterns to email development, while Resend handles reliable delivery.

**Core principles:**

1. **Server-side only** - Never expose API keys to clients 2. **Typed templates** - Props interfaces catch errors at compile time 3. **Reliable delivery** - Error handling with retry logic for transient failures 4. **Non-blocking** - Fire-and-forget for non-critical emails

**When to send emails:**

• User authentication events (verification, password reset, 2FA)
• Transactional confirmations (purchases, signups, invitations)
• Important notifications (security alerts, account changes)
• Team collaboration (invites, mentions, updates)

**When NOT to send emails:**

• Every minor action (creates email fatigue)
• Marketing without consent (spam, illegal)
• Real-time alerts (use push notifications)
• In-app actions (show in-app notifications instead)

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Email Template Structure

Define typed props, use React Email components, add PreviewProps for the dev server.

interface WelcomeEmailProps {
  userName: string;
  loginUrl: string;
  features?: string[];
}

export function WelcomeEmail({ userName, loginUrl, features = [] }: WelcomeEmailProps) {
  return (
    <BaseLayout preview={`Welcome, ${userName}!`}>
      <Heading>Welcome!</Heading>
      <Text>Hi {userName},</Text>
      <Button href={loginUrl}>Get Started</Button>
    </BaseLayout>
  );
}

WelcomeEmail.PreviewProps = { userName: "John", loginUrl: "..." } satisfies WelcomeEmailProps;

See [examples/core.md](examples/core.md) Pattern 1 for complete template with layout and styling.

---

Pattern 2: Sending with Error Handling

Always await `render()`, check the `{ data, error }` response, return typed results.

const html = await render(options.react); // CRITICAL: must await

const { data, error } = await resend.emails.send({
  from: `${DEFAULT_FROM_NAME} <${DEFAULT_FROM_ADDRESS}>`,
  to: options.to,
  subject: options.subject,
  html,
});

if (error) {
  return { success: false, error: error.message };
}
return { success: true, id: data?.id };

See [examples/core.md](examples/core.md) Pattern 2-3 for complete send wrapper and retry with exponential backoff.

---

Pattern 3: Async (Fire-and-Forget) Sending

For non-critical emails (welcome, notifications), don't block the response.

// Non-blocking - catches errors internally
sendEmailAsync(options);
return Response.json({ success: true }); // Returns immediately

Track in-flight promises for graceful shutdown. See [examples/async-batch.md](examples/async-batch.md) Pattern 1-2.

---

Pattern 4: Batch API

Use `resend.batch.send()` for 2-100 recipients. Render all templates in parallel.

const rendered = await Promise.all(
  emails.map(async (e) => ({
    from,
    to: e.to,
    subject: e.subject,
    html: await render(e.react),
  })),
);
const { data, error } = await resend.batch.send(rendered);

**Batch limitations:** No `attachments`, no `scheduledAt`. Tags and idempotency keys are supported. See [examples/async-batch.md](examples/async-batch.md) Pattern 3-4.

---

Pattern 5: Webhook Verification

Use `resend.webhooks.verify()` with the raw request body. JSON parsing breaks signature verification.

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

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!,
});