react-email

Build and send HTML emails using React components. A modern, component-based approach to email development that works across all major email clients.

npm i react-email

Or scaffold a new project:

npx create-email@latest
cd react-email-starter
npm install
npm run dev

This works with any package manager (npm, yarn, pnpm, bun) — substitute accordingly.

The dev server runs at localhost:3000 with a preview interface for templates in the emails folder.

Create an email component with proper structure using the Tailwind component for styling:

import {
  Html,
  Head,
  Preview,
  Body,
  Container,
  Heading,
  Text,
  Button,
  Tailwind,
  pixelBasedPreset
} from 'react-email';

interface WelcomeEmailProps {
  name: string;
  verificationUrl: string;
}

export default function WelcomeEmail({ name, verificationUrl }: WelcomeEmailProps) {
  return (
    <Html lang="en">
      <Tailwind
        config={{
          presets: [pixelBasedPreset],
          theme: {
            extend: {
              colors: {
                brand: '#007bff',
              },
            },
          },
        }}
      >
        <Head />
        <Body className="bg-gray-100 font-sans">
          <Preview>Welcome - Verify your email</Preview>
          <Container className="max-w-xl mx-auto p-5">
            <Heading className="text-2xl text-gray-800">
              Welcome!
            </Heading>
            <Text className="text-base text-gray-800">
              Hi {name}, thanks for signing up!
            </Text>
            <Button
              href={verificationUrl}
              className="bg-brand text-white px-5 py-3 rounded block text-center no-underline box-border"
            >
              Verify Email
            </Button>
          </Container>
        </Body>
      </Tailwind>
    </Html>
  );
}

// Preview props for testing
WelcomeEmail.PreviewProps = {
  name: 'John Doe',
  verificationUrl: 'https://example.com/verify/abc123'
} satisfies WelcomeEmailProps;

export { WelcomeEmail };

• When iterating over the code, only update what the user asked for. Keep the rest intact.
• If the user asks to use media queries, inform them that most email clients don't support them and suggest a different approach.
• Never use template variables (like {{name}}) directly in TypeScript code. Instead, reference the underlying properties directly. If the user explicitly asks for {{variableName}}, place the mustache string only in PreviewProps, never in the component JSX:

const EmailTemplate = (props) => {
  return (
    <h1>Hello, {props.variableName}!</h1>
  );
}

EmailTemplate.PreviewProps = {
  variableName: "{{variableName}}",
};

export default EmailTemplate;

• Never write the {{variableName}} pattern directly in the component structure. If the user insists, explain that this would make the template invalid.

See references/COMPONENTS.md for complete component documentation.

Core Structure:

• Html - Root wrapper with lang attribute
• Head - Meta elements, styles, fonts
• Body - Main content wrapper
• Container - Outermost centering wrapper (has built-in max-width: 37.5em). Use only once per email.
• Section - Interior content blocks (no built-in max-width). Use for grouping content inside Container.
• Row & Column - Multi-column layouts
• Tailwind - Enables Tailwind CSS utility classes

Content:

• Preview - Inbox preview text, always first inside <Body>
• Heading - h1-h6 headings
• Text - Paragraphs
• Button - Styled link buttons (always include box-border)
• Link - Hyperlinks
• Img - Images (see Static Files section below)
• Hr - Horizontal dividers

Specialized:

• CodeBlock - Syntax-highlighted code
• CodeInline - Inline code
• Markdown - Render markdown
• Font - Custom web fonts

When a user requests an email template, ask clarifying questions FIRST if they haven't provided:

1. Brand colors - Ask for primary brand color (hex code like #007bff)
2. Logo - Ask if they have a logo file and its format (PNG/JPG only - warn if SVG/WEBP)
3. Style preference - Professional, casual, or minimal tone
4. Production URL - Where will static assets be hosted in production?

See references/STYLING.md for comprehensive styling documentation including typography, layout patterns, dark mode, and brand consistency.

React Email supports sending with any email service provider. See references/SENDING.md for complete sending documentation including Resend, Nodemailer, and SendGrid examples.

Quick example using the Resend SDK:

import { Resend } from 'resend';
import { WelcomeEmail } from './emails/welcome';

const resend = new Resend(process.env.RESEND_API_KEY);

const { data, error } = await resend.emails.send({
  from: 'Acme <onboarding@resend.dev>',
  to: ['user@example.com'],
  subject: 'Welcome to Acme',
  react: <WelcomeEmail name="John" verificationUrl="https://example.com/verify" />
});

The Resend Node SDK automatically handles both HTML and plain-text rendering.

The react-email package provides a CLI accessible via the email command:

See references/I18N.md for complete i18n documentation. React Email supports three libraries: next-intl, react-i18next, and react-intl.

React Email includes a visual editor (@react-email/editor) that can be embedded in your app. It's built on TipTap/ProseMirror and produces email-ready HTML.

See references/EDITOR.md for complete documentation including:

• EmailEditor — batteries-included component with bubble menus, slash commands, and theming
• StarterKit — 35+ email-aware extensions (headings, lists, tables, columns, buttons, etc.)
• Inspector — contextual sidebar for editing styles
• EmailTheming — built-in themes (basic, minimal) with customizable CSS properties
• composeReactEmail — export editor content to email-ready HTML and plain text
• Custom extensions via EmailNode and EmailMark

Quick example:

import { EmailEditor, type EmailEditorRef } from '@react-email/editor';
import '@react-email/editor/themes/default.css';
import { useRef } from 'react';

export function MyEditor() {
  const ref = useRef<EmailEditorRef>(null);

  return (
    <EmailEditor
      ref={ref}
      content="<p>Start typing...</p>"
      theme="basic"
    />
  );
}

See references/PATTERNS.md for complete examples including:

• Password reset emails
• Order confirmations with product lists
• Notification emails with code blocks
• Multi-column layouts
• Team invitation emails

1. Test across email clients - Gmail, Outlook, Apple Mail, Yahoo Mail
2. Keep it responsive - Max-width around 600px, test on mobile
3. Use absolute image URLs - Host on reliable CDN
4. Write meaningful alt text - Describe purpose and details for content images; use alt="" for decorative images (spacers, dividers, background flourishes). React Email's <Img> defaults to alt="".
5. Provide plain text version - Required for accessibility
6. Keep file size under 102KB - Gmail clips larger emails
7. Add proper TypeScript types - Define interfaces for all email props
8. Include preview props - Add .PreviewProps for development testing
9. Use verified domains - For production from addresses

• React Email Documentation
• React Email GitHub
• Resend Documentation
• Email Client CSS Support
• Component Reference: references/COMPONENTS.md
• Styling Guide: references/STYLING.md
• Email Editor: references/EDITOR.md
• Sending Guide: references/SENDING.md
• Internationalization Guide: references/I18N.md
• Common Patterns: references/PATTERNS.md