Common Email Patterns

Relevant source files

The following files were used as context for generating this wiki page:

• skills/react-email/references/PATTERNS.md
• apps/demo/emails/01-Barebone/welcome.tsx
• apps/demo/emails/01-Barebone/password-reset.tsx
• skills/react-email/SKILL.md
• skills/react-email/references/COMPONENTS.md
• skills/react-email/references/STYLING.md
• apps/demo/emails/Community/newsletters/codepen-challengers.tsx
• apps/demo/emails/05-Studio/welcome.tsx

Common Email Patterns represent standard architectural and design structures used to build functional React Email templates. These patterns cover transactional messages, newsletters, and notification systems, ensuring cross-client compatibility and responsive behavior.

Developers use these patterns to handle common requirements such as password resets, welcome sequences, and multi-column content layouts while adhering to email client limitations.

Sources: skills/react-email/SKILL.md:395-401, README.md:12-16

Core Structural Patterns

Every email pattern follows a specific component hierarchy to ensure proper rendering across different email clients.

The Container-Section Hierarchy

Patterns prioritize a single Container for the main content to enforce a consistent max-width (defaulting to 37.5em). Developers use Section components inside the Container to group related content blocks, such as headers, body text, and footers.

The diagram shows the standard component nesting required for a stable email layout.
Sources: skills/react-email/SKILL.md:104-108, skills/react-email/references/COMPONENTS.md:103-118

Multi-Column Layouts

Email patterns avoid CSS Flexbox and Grid due to lack of support in clients like Outlook. Instead, they use Row and Column components. A Column must always reside within a Row.

Layout Feature	Component Usage	Requirement
Horizontal Alignment	Row	Wraps multiple columns
Vertical Separation	Column	Must specify width (e.g., w-1/2)
Vertical Alignment	Column	Use align-top or align-middle

Sources: skills/react-email/references/COMPONENTS.md:129-143, skills/react-email/references/STYLING.md:102-108

Transactional Email Patterns

Transactional patterns focus on high-priority user actions and personalization.

Welcome and Onboarding

Welcome emails introduce users to a service. They typically include a hero image, a personalized greeting using props, and a prominent call-to-action (CTA) button.

• Hero Image: Set to w-full and h-auto for responsiveness.
• Personalization: Props are passed to the component; mustache syntax (e.g., {{name}}) is restricted to PreviewProps.
• CTA Button: Always includes box-border to prevent padding issues in Outlook.

Sources: skills/react-email/SKILL.md:43-69, apps/demo/emails/05-Studio/welcome.tsx:43-85

Password Reset and Notifications

These patterns emphasize clarity and security. They often use a minimal layout with a Heading, Text, and a single Button. Security notifications may also include a CodeBlock wrapped in a div with overflow-auto to display sensitive data or verification codes.

Sources: skills/react-email/SKILL.md:395-401, skills/react-email/references/COMPONENTS.md:255-263

Newsletter and Content-Rich Patterns

Content-rich patterns handle complex data structures like article lists, feature highlights, and resource links.

The "Featured Content" Pattern

Used in newsletters, this pattern utilizes Section blocks with borders and background colors to distinguish between different types of content (e.g., "This week's challenge" vs. "Resources").

This structure demonstrates how Row and Column facilitate side-by-side content blocks in a newsletter.
Sources: apps/demo/emails/Community/newsletters/codepen-challengers.tsx:112-205, apps/demo/emails/02-Matte/welcome.tsx:94-124

Administrative and Footer Patterns

The footer pattern provides essential compliance information and secondary links.

Mandatory Footer Elements

Every email pattern must include a footer section that provides the following:

1. Physical Address: The sender's registered address.
2. Unsubscribe Link: A Link component for opting out.
3. Copyright: The current year and company name.

<Section className="text-center text-gray-500 text-sm">
  <Text className="m-0">123 Main St, City, State 12345</Text>
  <Text className="m-0">&copy; {new Date().getFullYear()} Company Name</Text>
  <Link href={unsubscribeUrl}>Unsubscribe</Link>
</Section>

Sources: skills/react-email/references/STYLING.md:65-71, apps/demo/emails/05-Studio/welcome.tsx:162-177

Asset Handling Patterns

Handling images requires specific patterns to work in both development and production environments.

The Base URL Pattern

Templates use a baseURL constant that checks NODE_ENV. This ensures images load from the local static folder during development and from a CDN in production.

const baseURL = process.env.NODE_ENV === "production"
  ? "https://cdn.example.com"
  : "";

<Img
  src={`${baseURL}/static/logo.png`}
  alt="Company Logo"
  width="150"
  height="50"
/>

Sources: skills/react-email/SKILL.md:144-162, apps/demo/emails/05-Studio/welcome.tsx:21-23

Image Accessibility

• Meaningful Images: Patterns require descriptive alt text.
• Decorative Images: Patterns require an explicit alt="" so screen readers skip them.
• Linked Images: If an Img is inside a Link, the alt text must describe the destination, not the image itself.

Sources: skills/react-email/SKILL.md:329-338, skills/react-email/references/STYLING.md:88-100

Common Email Patterns standardize the development of React Email templates by enforcing structural hierarchies, mobile-first styling, and accessible asset management. These patterns ensure that complex layouts remain functional and visually consistent across the fragmented ecosystem of email clients.