React Email templates let developers author transactional messages with familiar React components while still producing the conservative HTML that email clients expect. The key is to treat your template as one part of a complete delivery system: render it deterministically, provide a text alternative, validate data, authenticate the sending domain, and monitor what happens after handoff.

What React Email templates are—and what they are not

React Email is a component toolkit and rendering workflow for building email markup with React. Rather than sending a browser-rendered React application to an inbox, you create a React component tree and render it on the server into an HTML string suitable for an email message. React Email's documentation describes this provider-neutral model directly: to use it with an email service, render the component into HTML first. (react.email)

That distinction matters. An email client is not a browser tab. Many inboxes constrain CSS, strip scripts, block remote images until a recipient opts in, alter dark-mode colors, and use rendering engines that lag behind modern web standards. React is useful here because it gives you composition, typed props, reusable modules, and tests—not because recipients can execute JSX.

A good mental model is:

Your application prepares trusted data for a message, such as an order number, a reset URL, or a recipient's first name.
A React component turns that data into a stable document using email-safe primitives.
A renderer produces HTML and plain text for a multipart email.
A transactional provider or SMTP relay accepts the message and attempts delivery.
Receiving systems evaluate authentication, content, reputation, and recipient policy before deciding whether to accept, defer, filter, or reject it.

React Email solves the authoring and rendering portion elegantly. It does not by itself verify a domain, warm an IP, handle bounce webhooks, establish a sending reputation, or guarantee inbox placement. Those remain responsibilities of your email infrastructure and operational process.

For a provider-neutral architecture, keep templates in your own codebase and send rendered output through a REST API or an authenticated SMTP relay. That makes the template layer portable: changing providers should not require rewriting business-critical emails. When you need implementation references for a REST- or SMTP-based integration, consult the provider's email API setup guides rather than coupling React components to a proprietary template format.

When React Email is a strong fit

React Email templates are particularly useful when emails are part of an application workflow and must evolve with the product. Password resets, verification links, receipts, invitations, alerts, account updates, support notifications, and B2B workflow events tend to benefit from source-controlled templates.

Benefits for application teams

The largest advantage is maintainability. A shared EmailLayout, BrandHeader, PrimaryButton, or Footer can be used across dozens of messages. Updating a logo URL, legal address, support link, or baseline typography becomes a small reviewed code change instead of a series of edits in disconnected HTML files.

Typed props also reduce production mistakes. A TypeScript interface can make an InvoiceEmail require an invoice number, a due date, an amount, and a payment URL. Missing critical variables become build-time or test-time failures instead of an email containing {{customer_name}} or the string undefined.

Component composition makes variation easier without turning templates into a maze of conditionals. A single receipt layout can accept line items, an optional discount row, payment status, and a localized footer. Keep the decision logic in the application or in small presentational components; do not bury database access or permission logic in the email template.

Cases where another approach may be better

A React-based workflow is not automatically the best choice for every email. A marketing team that needs to assemble campaigns daily without a deployment process may prefer a controlled visual editor or a campaign platform. A nontechnical operations team may need a template system with approvals, localization controls, and role-based editing.

There is also a middle ground. Developers can define a React-based design system and expose only safe content fields to a visual editing layer. The important boundary is that untrusted or user-authored content must not become arbitrary HTML in a transactional message.

Set up a project and choose a rendering boundary

React Email's current getting-started documentation recommends create-email for automatic project setup, using npx create-email@latest. Its current package direction also uses the unified react-email package for components and rendering utilities. (react.email)

For an existing Node.js or TypeScript application, install the rendering dependencies in the service that will create messages. Keep email templates outside browser-only code so rendering does not accidentally depend on DOM APIs, client hooks, or browser environment variables.

A simple structure might look like this:

src/
  emails/
    components/
      EmailLayout.tsx
      PrimaryButton.tsx
    AccountWelcome.tsx
    PasswordReset.tsx
    OrderReceipt.tsx
  email/
    render.ts
    send.ts
    templates.test.tsx

The boundary should be explicit: template files accept plain data and return a React element; a rendering module turns that element into strings; a sending module knows how to speak to your provider. Keeping these responsibilities separate gives you cleaner tests and makes migrations much less risky.

A minimal, reusable template

The following example uses the unified react-email import style shown in current React Email materials. It intentionally uses straightforward elements and inline style objects because email client compatibility is more valuable than clever CSS.

import {
  Body,
  Button,
  Container,
  Head,
  Heading,
  Html,
  Preview,
  Section,
  Text,
} from "react-email";

type PasswordResetEmailProps = {
  firstName: string;
  resetUrl: string;
  expiresInMinutes: number;
};

export function PasswordResetEmail({
  firstName,
  resetUrl,
  expiresInMinutes,
}: PasswordResetEmailProps) {
  return (
    <Html lang="en">
      <Head />
      <Preview>Reset your account password</Preview>
      <Body style={styles.body}>
        <Container style={styles.container}>
          <Heading style={styles.heading}>Reset your password</Heading>
          <Text style={styles.text}>Hello {firstName},</Text>
          <Text style={styles.text}>
            We received a request to reset your password. Use the button
            below to choose a new one.
          </Text>
          <Section style={styles.buttonRow}>
            <Button href={resetUrl} style={styles.button}>
              Reset password
            </Button>
          </Section>
          <Text style={styles.muted}>
            This link expires in {expiresInMinutes} minutes. If you did not
            request a password reset, you can ignore this email.
          </Text>
        </Container>
      </Body>
    </Html>
  );
}

const styles = {
  body: {
    backgroundColor: "#f6f7f9",
    fontFamily: "Arial, sans-serif",
    margin: "0",
    padding: "24px 0",
  },
  container: {
    backgroundColor: "#ffffff",
    borderRadius: "8px",
    margin: "0 auto",
    maxWidth: "560px",
    padding: "32px",
  },
  heading: { color: "#111827", fontSize: "24px", lineHeight: "32px" },
  text: { color: "#374151", fontSize: "16px", lineHeight: "24px" },
  buttonRow: { padding: "8px 0 16px" },
  button: {
    backgroundColor: "#2563eb",
    borderRadius: "6px",
    color: "#ffffff",
    display: "inline-block",
    fontSize: "16px",
    fontWeight: "600",
    padding: "12px 18px",
    textDecoration: "none",
  },
  muted: { color: "#6b7280", fontSize: "14px", lineHeight: "20px" },
};

This is deliberately boring markup. That is usually a virtue in email. The <Preview> component supplies inbox preview text, while <Html>, <Head>, <Body>, and layout components make the message structure clear. React Email provides standard components intended to reduce the burden of maintaining email-oriented markup, including layouts that account for the table-heavy realities of inbox rendering. (react.email)

Render both HTML and plain text

HTML should not be the only representation of an important transactional email. A proper multipart message commonly includes an HTML part and a text/plain part. The text version helps recipients whose clients cannot display HTML, recipients using accessibility-focused reading setups, and deliverability diagnostics that evaluate whether the message has a coherent non-HTML fallback.

React Email's render utility is designed to transform components into HTML email templates and supports plain-text conversion as part of the workflow. The project explicitly notes that plain-text versions matter when a recipient cannot view HTML. (react.email)

A rendering adapter can look like this:

import { render } from "react-email";
import { PasswordResetEmail } from "../emails/PasswordReset";

export async function renderPasswordReset(input: {
  firstName: string;
  resetUrl: string;
  expiresInMinutes: number;
}) {
  const element = (
    <PasswordResetEmail
      firstName={input.firstName}
      resetUrl={input.resetUrl}
      expiresInMinutes={input.expiresInMinutes}
    />
  );

  const html = await render(element);
  const text = await render(element, { plainText: true });

  return {
    subject: "Reset your password",
    html,
    text,
  };
}

Exact provider payload names vary, but the conceptual send request is consistent:

const message = await renderPasswordReset({
  firstName: "Avery",
  resetUrl: "https://app.example.com/reset?token=...",
  expiresInMinutes: 30,
});

await emailClient.send({
  from: "Example App <security@example.com>",
  to: ["avery@example.net"],
  subject: message.subject,
  html: message.html,
  text: message.text,
});

Do not render on the client and then post arbitrary HTML to your backend. Render sensitive transactional emails in a trusted server environment. The server should own API keys, SMTP credentials, signing configuration, personalization data, and authorization checks.

Treat rendering as a deterministic build step

For a given component and props object, rendering should produce predictable output. That means avoiding unstable values such as new Date() scattered inside components, random IDs in markup, client-side locale detection, and network requests during render.

Instead, calculate dynamic values before rendering:

const issuedAt = new Date();
const expiresAt = new Date(issuedAt.getTime() + 30 * 60 * 1000);

await renderPasswordReset({
  firstName: user.firstName,
  resetUrl,
  expiresInMinutes: Math.round((expiresAt.getTime() - issuedAt.getTime()) / 60000),
});

This approach makes previewing, snapshot testing, retrying failed sends, and auditing production messages significantly easier.

Design for email clients, not the modern web

The biggest template mistake is assuming an inbox behaves like Chrome, Safari, or Firefox. An email that appears polished in a local browser preview can degrade badly in Outlook desktop, Gmail mobile, a dark-mode inbox, or a client that strips a CSS feature.

Use conservative layout rules

Prefer a single-column layout for essential transactional content. Use a constrained content width—roughly 560 to 640 pixels is common—and make the primary action obvious. If you need columns, ensure the content still makes sense when columns stack or styles fail.

Favor:

Table-oriented or email-library layout components for structural regions.
Inline styles for critical presentation.
Explicit pixel sizes for key spacing and buttons.
Absolute HTTPS URLs for links and image sources.
A real text link near an important button, especially for security-sensitive flows.
Sufficient color contrast and readable body text.

Avoid relying on JavaScript, form controls, hover states, video playback, external stylesheets, CSS Grid, complex positioning, and background-image-only content. Support varies, and even supported features may be altered by security filtering.

Make buttons and links resilient

Every call to action should use an absolute URL, such as https://app.example.com/invoices/inv_123. Relative paths such as /invoices/inv_123 do not have a site origin in an inbox and will fail.

For password resets, invites, and verification links, include a visible fallback URL or a concise instruction to copy the link if the button does not work. Do not expose raw long-lived secrets in a link. Use single-purpose, time-limited tokens, store only a secure verifier where appropriate, and invalidate the token after use.

Account for dark mode and image blocking

Do not encode meaning solely in a logo, an image, or a color. A green success badge should also say “Payment received”; a red warning banner should include clear text. Provide meaningful alt text for functional images, and make sure the email still conveys its core message if every remote image is blocked.

Dark mode may invert or reinterpret colors. Test light text on dark backgrounds, colored logos with transparent backgrounds, and buttons with low-contrast borders. There is no single dark-mode rule that works identically everywhere, so graceful degradation is the objective.

Personalization, localization, and security boundaries

React components make personalization pleasant, but templates often sit at a security boundary. Recipient names, product names, support messages, comment excerpts, and organization labels can originate outside your codebase. Handle them as data, not markup.

Escape by default and avoid unsafe HTML

React escapes string content by default when rendered into normal JSX text nodes. Keep that protection. Do not use dangerouslySetInnerHTML for names, comments, or any data entered by a customer unless you have a carefully defined sanitization policy.

If a product truly requires rich user-authored content, sanitize it server-side with an allowlist tailored for email: a small set of text formatting tags, safe absolute links, no scripts, no event attributes, no embedded frames, and no untrusted styles. Then test the sanitized result in actual inboxes. Most transactional templates are better when user content is represented as plain text.

Validate URLs before inserting them

A link prop is not just a string. Confirm that an action URL uses https:, belongs to an expected host where appropriate, and contains an intended path. Avoid turning customer-provided strings directly into href values.

A useful policy is:

Generate security-sensitive links on the server.
Use HTTPS for all customer-facing destinations.
Permit only approved domains for account and billing actions.
Add tracking parameters only if they do not expose sensitive identifiers.
Never put passwords, session cookies, API keys, or full payment data in query parameters.

Localize outside the layout layer

Pass localized strings and formatted values into templates rather than formatting every value inline. Dates, currencies, plurals, and right-to-left language support need deliberate handling. A receipt template should receive a locale-aware amount such as $49.00 or 49,00 €, not a raw minor-unit integer that each component guesses how to display.

Also localize the subject and preview text. Inbox preview text is part of the recipient experience, not merely an implementation detail.

Send through HTTP APIs or SMTP without coupling templates to a provider

Once you have html, text, subject, recipients, and headers, either a transactional email HTTP API or an authenticated SMTP relay can deliver the message. Both are valid integration paths.

An HTTP API typically gives structured responses, easier attachment handling, idempotency options when supported, webhooks, and a direct request/response model. SMTP is a standard relay protocol and can be useful for legacy applications, frameworks with mature SMTP adapters, or environments where a conventional mail transport is easier to operate.

Use idempotency and an outbox pattern

The most dangerous failure mode is ambiguity: your application times out after submitting a message, but the provider may have accepted it. Blindly retrying can send duplicate receipts or password-reset emails.

Store a durable outbound-email record before sending. Include an internal event ID, template version, recipient, subject, rendered-content hash, provider message ID when available, status, and attempt count. If your provider supports idempotency keys, derive a key from the business event, such as receipt:order_12345.

A robust lifecycle looks like this:

Commit the business event and outbound-email job together when your architecture allows it.
Render the template in a worker with validated input.
Submit the message once with an idempotency key or equivalent deduplication guard.
Persist the provider response and message identifier.
Retry only transient failures under bounded backoff.
Process delivery, bounce, complaint, and suppression events separately from submission success.

Interpret responses correctly

A successful API response or SMTP 250 response usually means the relay accepted responsibility for the message. It does not mean the recipient opened it, that it landed in the inbox, or even that the destination server ultimately accepted it.

SMTP reply classes provide a useful baseline. Replies beginning with 2 indicate success; replies beginning with 4 are transient failures that may be retried; replies beginning with 5 are permanent failures that generally need correction rather than immediate retry. RFC 5321 describes 550 as a common reply when a mailbox is known not to be deliverable. (rfc-editor.org)

Examples you may encounter include:

250 2.0.0: Message accepted by the SMTP server.
421 4.7.0: Service temporarily unavailable or connection-related deferral; retry with backoff.
450 4.2.0: Mailbox or recipient system temporarily unavailable; retry later.
451 4.7.1: Temporary local or policy-related processing failure; retry, then inspect the enhanced status and provider guidance.
452 4.2.2: Insufficient system storage or a related temporary capacity issue; retry later.
550 5.1.1: Commonly an invalid or nonexistent recipient mailbox; suppress or correct the address.
552 5.2.2: Often indicates a mailbox storage problem; treat according to the receiving system's wording and your provider's bounce classification.
554 5.7.1: Often a policy rejection, potentially tied to authentication, content, reputation, or recipient rules; do not repeatedly retry without investigation.

The human-readable portion and enhanced status code matter. Do not write retry logic based only on the numeric code from a single provider because providers can map delivery outcomes differently.

Authenticate the domain that sends your React Email templates

A polished template cannot overcome missing authentication. Receiving systems evaluate the identity of the message independently of the HTML. Set up SPF, DKIM, and DMARC for the domain or subdomain used in the visible From: address, then verify the records after DNS propagation.

SPF record syntax

SPF is published as a DNS TXT record at the sending domain. The following is syntactically valid but illustrative because 192.0.2.0/24 is documentation-only address space, not a real sending network:

example.com. IN TXT "v=spf1 ip4:192.0.2.0/24 -all"

In a real setup, your transactional provider will give you an exact mechanism—often an include: value or a delegated subdomain—and you should use that exact value. Do not guess it. An example shape is:

example.com. IN TXT "v=spf1 include:provider-authorized.example -all"

Publish one SPF TXT record for a domain. Multiple SPF records can cause a PermError. Also remember that SPF has a DNS lookup limit, so every additional include should be intentional. Use a distinct subdomain such as mail.example.com or notify.example.com if separating transactional and marketing traffic improves operational control.

DKIM record syntax

DKIM signs messages cryptographically. The provider or your own signing system chooses a selector, then you publish the public key at <selector>._domainkey.<domain>. A record has this general form:

s1._domainkey.example.com. IN TXT "v=DKIM1; k=rsa; p=BASE64_ENCODED_PUBLIC_KEY"

The selector and complete public key must come from the actual signer. Never substitute a shortened or invented production key. Many providers use CNAME records for DKIM delegation instead of asking you to paste a TXT key; follow the exact record type, host, and target they supply. MXToolbox offers a DKIM lookup that checks a published selector and domain for a valid key record. (mxtoolbox.com)

DMARC record syntax and alignment

DMARC is published at _dmarc.<domain> and expresses a policy for messages that fail DMARC evaluation. A cautious monitoring record is:

_dmarc.example.com. IN TXT "v=DMARC1; p=none; rua=mailto:dmarc-reports@example.com; pct=100"

A later enforcement posture could be:

_dmarc.example.com. IN TXT "v=DMARC1; p=quarantine; rua=mailto:dmarc-reports@example.com; pct=100"

Or, after you have verified all legitimate senders and their alignment:

_dmarc.example.com. IN TXT "v=DMARC1; p=reject; rua=mailto:dmarc-reports@example.com; pct=100"

DMARC requires alignment between the domain visible in From: and either an authenticated SPF domain or a DKIM signing domain, depending on the passing authentication path. Start with p=none, examine aggregate reports, inventory every legitimate sending system, then move gradually toward enforcement. RFC 7489 defines the _dmarc record form and gives a zone-file example beginning with v=DMARC1; p=none; rua=mailto:.... (rfc-editor.org)

Validate before blaming the template

Use DNS tools to verify what authoritative nameservers return, rather than relying only on a DNS dashboard's “saved” state. MXToolbox provides SPF, DKIM, TXT, and MX diagnostics; its TXT lookup queries authoritative nameservers. (mxtoolbox.com)

Authentication must be tested with a real delivered message too. Inspect the received message headers and look for authentication results showing SPF, DKIM, and DMARC passes. A record that exists in DNS can still fail because the envelope sender, DKIM d= domain, and visible From: domain are not aligned as expected.

Test the rendered message and the delivery path

Email testing needs both code-level and mailbox-level checks. A snapshot proves that your renderer did not unexpectedly change markup; it does not prove Gmail, Outlook, or Apple Mail will display it as intended.

Test at four levels

Unit test component data. Verify conditional blocks, pluralization, subject creation, required props, and output for edge cases such as long names or missing optional fields.
Snapshot rendered HTML and text. Render a stable fixture and review intentional changes in pull requests. Normalize nondeterministic content first.
Visual-test representative inboxes. Send to test accounts across major clients and device types. Check layout, clipping, dark mode, image blocking, link behavior, and fallback text.
Test deliverability and headers. Send a real message to mail-tester.com, which generates a test address and analyzes the message, server, and configuration after receipt. (mail-tester.com)

Do not test only the happy path. Create fixtures for a 100-character recipient name, ten line items, a right-to-left locale, a no-image environment, an expired link, a very small mobile viewport, and a recipient whose client displays only plain text.

Check links, images, and content size

Automated tests should extract every href and src from rendered HTML. Confirm that links are HTTPS, belong to approved hosts where necessary, and do not contain development domains. Verify image URLs return expected content and that unsubscribe or support links appear where the email class requires them.

Keep transactional emails focused. A receipt with ten external tracking pixels, several oversized images, and an unnecessary application bundle is slower, harder to troubleshoot, and more likely to look suspicious. The primary message should remain understandable without remote images or tracking.

Common failure modes and how to prevent them

The same issues recur across providers because they are usually application and mail-protocol problems rather than vendor-specific defects.

Sending the React element instead of rendered output

A React component is not an email body. Render to HTML before calling an HTTP API or composing a MIME message for SMTP. If a provider's SDK accepts a React element directly, understand that it is doing a rendering step for you; retaining your own render path can still make portability and tests clearer.

Missing text fallback

A text-only version is not a relic. It improves resilience and can make security-sensitive content easier to inspect. Ensure the plain-text output includes the action URL, expiry information, support instructions, and any important identifiers.

Styling that works only in preview

Preview tools are useful but not authoritative. A template that relies on a browser-only CSS behavior may be rearranged or stripped in a mailbox. Start with the constraints, then add polish that degrades gracefully.

Confusing queued, accepted, delivered, and opened

These are different events. “Queued” means your application stored a job. “Accepted” means the relay took responsibility. “Delivered” usually means the destination provider accepted it. “Opened” is an imperfect measurement that may depend on remote image loading and privacy features. Keep these states separate in data models and support tooling.

Retrying permanent failures

Retrying a transient 4xx response can be reasonable. Repeatedly retrying a hard invalid-recipient or policy failure wastes resources and can harm reputation. Build a suppression process for hard bounces and complaints, and distinguish them from temporary delays.

Editing a template without a version strategy

Store a template identifier and version with every sent message. If a customer contacts support about a confusing receipt, you need to know which copy, locale, layout, and business event generated it. Versioning also lets teams roll back a problematic design without guessing which deployment introduced it.

Operational practices for reliable transactional email

The template is a product surface and an infrastructure artifact. Treat it with the same operational discipline as an API response or payment confirmation page.

Build an observability trail

For each attempted send, record at least:

Internal event ID and idempotency key.
Template name and version.
Recipient domain, but minimize unnecessary retention of personal data.
Sender domain and reply-to address.
Provider submission ID or SMTP queue ID when available.
Attempt timestamps, response codes, enhanced status codes, and error text.
Delivery, bounce, complaint, and suppression events.

This data turns “the email never arrived” from a vague support ticket into a diagnosable flow. You can determine whether no job was created, rendering failed, the provider rejected submission, the recipient server deferred it, the mailbox bounced, or the message was accepted but filtered.

Separate message classes when appropriate

Password resets, account alerts, receipts, and bulk product announcements should not necessarily share the same sending stream, subdomain, or operational rules. Transactional messages are generally expected and time-sensitive; marketing traffic has different consent, cadence, and engagement dynamics.

A separate transactional subdomain can make DNS configuration, reporting, and incident response clearer. But separation is not a substitute for good list hygiene, correct authentication, relevant content, and a controlled sending pattern.

Keep reply handling intentional

Choose a real Reply-To: address when recipients may need help. For no-reply security messages, provide a clear support path in the body. Do not make a message look conversational if replies disappear into an unmonitored mailbox.

Use a recognizable sender name and stable from-domain. Sudden identity changes can confuse recipients and complicate authentication troubleshooting.

A practical production checklist

Before shipping a new React Email template, review this list:

Conclusion

React Email templates are a practical way to bring software-engineering discipline to transactional email: components for consistency, TypeScript for safer inputs, rendering for provider independence, and source control for reliable changes. But strong results come from the full system around the template.

Build conservative markup, render HTML and plain text, keep personalization data safe, send through a well-instrumented REST API or SMTP relay, and verify SPF, DKIM, and DMARC before diagnosing a layout problem as a deliverability problem. With those boundaries in place, your email templates can be both pleasant to maintain and dependable for recipients.

FAQ

Can React Email templates work with any transactional email provider?

Yes. React Email components are rendered into HTML, which can be sent through a provider's HTTP API or an authenticated SMTP relay. The provider-specific portion should be limited to the final send adapter, credentials, and delivery-event handling. (react.email)

Should I send HTML only, or include plain text too?

Include both. HTML provides the designed experience, while a plain-text part improves accessibility and resilience for clients that cannot or should not display HTML. React Email supports a plain-text rendering path. (react.email)

Does a successful API response mean the recipient received the email?

No. It normally means your provider accepted the message for processing. Final delivery can still be deferred, bounced, rejected by recipient policy, filtered into spam, or accepted without being opened.

Why do SPF, DKIM, and DMARC matter if my React Email template looks correct?

They establish and validate sender identity independently of the HTML design. Missing or misaligned authentication can lead receiving systems to distrust, filter, or reject an otherwise well-built message. DMARC also gives domain owners a policy and reporting framework for authentication failures. (rfc-editor.org)

What is the best way to test a React Email template before release?

Use layered tests: unit tests for data conditions, snapshots for rendered HTML and text, real inbox checks for visual compatibility, and a deliverability test address such as mail-tester.com for headers and configuration feedback. (mail-tester.com)

React Email Templates: Build, Render, Test, and Send Reliably