Demo
General
Email

Email Templates

Learn how to create and use React Email templates.

The starter kit uses React Email to create email templates using .tsx files. React Email allows you to leverage Tailwind CSS and React components while ensuring consistent email styling across various email clients.

Why React Email?

Creating Email Templates

Create email templates in the lib/email/templates/ directory:

lib/email/templates/welcome-email.tsx
import type * as React from 'react';
import {
  Body,
  Button,
  Container,
  Head,
  Heading,
  Html,
  Preview,
  Section,
  Text
} from '@react-email/components';
import { Tailwind } from '@react-email/tailwind';

export type WelcomeEmailProps = {
  name: string;
  welcomeLink: string;
};

function WelcomeEmail({
  name,
  welcomeLink
}: WelcomeEmailProps): React.JSX.Element {
  return (
    <Html>
      <Head />
      <Preview>Welcome to our platform!</Preview>
      <Tailwind>
        <Body className="m-auto bg-white px-2 font-sans">
          <Container className="mx-auto my-[40px] max-w-[465px] rounded-sm border border-[#eaeaea] border-solid p-[20px]">
            <Heading className="mx-0 my-[30px] p-0 text-center font-normal text-[24px] text-black">
              Welcome!
            </Heading>
            <Text className="text-[14px] text-black leading-[24px]">
              Hello {name},
            </Text>
            <Text className="text-[14px] text-black leading-[24px]">
              Thanks for joining us. We're excited to have you on board!
            </Text>
            <Section className="my-[32px] text-center">
              <Button
                href={welcomeLink}
                className="rounded-sm bg-[#000000] px-5 py-3 text-center font-semibold text-[12px] text-white no-underline"
              >
                Get Started
              </Button>
            </Section>
          </Container>
        </Body>
      </Tailwind>
    </Html>
  );
}

// Preview props for React Email preview
WelcomeEmail.PreviewProps = {
  name: 'John Doe',
  welcomeLink: 'https://example.com/dashboard'
} satisfies WelcomeEmailProps;

export default WelcomeEmail;
export { WelcomeEmail };

Registering Email Templates

After creating a template, add a method to the email service in lib/email/service.ts:

lib/email/service.ts
import { render } from "@react-email/render";
import type { WelcomeEmailProps } from "./templates/welcome-email";

public async sendWelcomeEmail(
  input: WelcomeEmailProps & { recipient: string },
): Promise<void> {
  const { WelcomeEmail } = await import(
    "./templates/welcome-email"
  );
  const component = WelcomeEmail(input);
  const html = await render(component);
  const text = await render(component, { plainText: true });

  await this.sendEmail({
    recipient: input.recipient,
    subject: "Welcome to our platform!",
    html,
    text,
  });
}

Using Email Templates

Send emails using the email service:

lib/actions/send-welcome.ts
import { emailService } from '@/lib/email';
import { getBaseUrl } from '@/lib/utils';

export async function sendWelcomeEmail(user: { email: string; name: string }) {
  await emailService.sendWelcomeEmail({
    recipient: user.email,
    name: user.name,
    welcomeLink: `${getBaseUrl()}/dashboard`
  });
}

Available Components

React Email provides many components for building emails:

  • Container - Main wrapper
  • Section - Content sections
  • Heading - Headings (h1-h6)
  • Text - Paragraph text
  • Button - Call-to-action buttons
  • Link - Hyperlinks
  • Image - Images
  • Hr - Horizontal rules
  • Code - Inline code
  • CodeBlock - Code blocks

See the React Email documentation for a complete list.

Styling

Using Tailwind

React Email supports Tailwind CSS:

lib/email/templates/example.tsx
<Tailwind>
  <Body className="bg-gray-100">
    <Container className="bg-white rounded-lg p-6">
      <Text className="text-lg font-bold text-blue-600">Hello World</Text>
    </Container>
  </Body>
</Tailwind>

Inline Styles

You can also use inline styles:

lib/email/templates/example.tsx
<Text style={{ fontSize: '16px', color: '#333' }}>Hello World</Text>

Preview Props

Each template should export PreviewProps for the React Email preview:

lib/email/templates/welcome-email.tsx
WelcomeEmail.PreviewProps = {
  name: 'John Doe',
  welcomeLink: 'https://example.com/dashboard'
} satisfies WelcomeEmailProps;

Previewing Emails

You can preview your email templates during development. See the React Email Preview documentation for details.

Running the Preview Server

Terminal
npm run email:dev

This starts a local server at http://localhost:3001 where you can preview all your email templates.

Available Templates

The starter kit includes the following email templates:

  • Verify Email Address - Email verification link
  • Password Reset - Password reset instructions
  • Organization Invitation - Invite users to organizations
  • Payment Failed - Notify about failed payments
  • Subscription Canceled - Notify about canceled subscriptions
  • Trial Ending Soon - Remind about trial expiration
  • Contact Form - Contact form submissions
  • Revoked Invitation - Notify about revoked invitations
  • Email Address Change - Confirm email address change

All templates are located in lib/email/templates/ and can be customized to match your brand.

Customizing Templates

Update Branding

Update the logo and colors in your templates:

lib/email/templates/welcome-email.tsx
<Container className="mx-auto my-[40px] max-w-[465px] rounded-sm border border-[#eaeaea] border-solid p-[20px]">
  <Image
    src="https://yourdomain.com/logo.png"
    alt="Your Company"
    width="120"
    height="40"
  />
  {/* ... rest of template */}
</Container>

Add Custom Styles

Create a shared styles file:

lib/email/styles.ts
export const emailStyles = {
  primaryColor: '#000000',
  secondaryColor: '#666666',
  borderRadius: '4px',
  fontFamily: 'Arial, sans-serif'
};

Use in templates:

lib/email/templates/example.tsx
import { emailStyles } from '../styles';

<Button
  style={{
    backgroundColor: emailStyles.primaryColor,
    borderRadius: emailStyles.borderRadius
  }}
>
  Click Me
</Button>;

Best Practices

  1. Use Preview Props - Always define preview props for development
  2. Test across clients - Test emails in Gmail, Outlook, Apple Mail
  3. Keep it simple - Avoid complex layouts that break in email clients
  4. Use Tailwind - Leverage Tailwind for consistent styling
  5. Include plain text - Always provide a plain text version
  6. Mobile responsive - Ensure emails look good on mobile devices
  7. Accessible - Use semantic HTML and alt text for images