Why Your Tailwind v4 Emails Break in Gmail

The quick fix

If you just need this working again, here are your options in order of effort:

1. Pin React Email to pre-v4 versions. The old @react-email/[email protected] used Tailwind v3 internally, which generated the legacy min-width syntax. This is a stopgap, not a long-term solution, but it'll get your emails working again in five minutes.
2. Wait for the upstream fix. I opened a PR on @react-email/tailwind that adds a downleveling step before CSS injection. Once merged, upgrading the package should fix it.
3. Switch to Maizzle. If you're not locked into React Email, Maizzle is built specifically for Tailwind + email. It runs Lightning CSS to downlevel modern syntax, replaces default breakpoints with email-safe equivalents, and handles OKLCH-to-RGB color conversion. More work upfront, but it avoids this entire class of problem.

What changed in Tailwind v4

Tailwind CSS v4 (January 2025) changed two things about its CSS output. Both are invisible in browsers but break email clients.

1. Range media query syntax

Tailwind v3 generated the legacy min-width form that email clients understand:

/* Tailwind CSS v3 — works in Gmail */
@media (min-width: 640px) {
  .sm\:bg-red-300 {
    background-color: #fca5a5;
  }
}

Tailwind v4 switched to Media Queries Level 4 range syntax:

/* Tailwind CSS v4 — silently ignored by Gmail */
.sm_bg-red-300 {
  @media (width >= 40rem) {
    background-color: rgb(255, 162, 162);
  }
}

Every modern browser supports (width >= 40rem). Gmail, Outlook, Yahoo, and Samsung Mail don't. They discard the entire rule.

2. CSS nesting

Look at the v4 output again. The @media rule is inside the selector. In v3 it was the other way around. This is CSS nesting. According to caniemail.com, no major email client fully supports it. Apple Mail has partial support (requires the explicit & selector). Everyone else ignores it.

So the output has two problems: the media query syntax is unrecognized, and the nesting structure is ignored. Both need to be fixed.

Why React Email is affected

In a normal web build (PostCSS, Vite, Next.js), Tailwind's output goes through Lightning CSS, which downlevels range syntax and unnests media queries automatically. The browser never sees the modern syntax.

React Email's <Tailwind> component calls compile().build() directly to get the CSS. That API returns raw output without the Lightning CSS step. The modern syntax goes straight into the <style> tag.

Maizzle doesn't have this problem because it uses the full PostCSS pipeline with a custom Tailwind CSS config that replaces default breakpoints and forces Lightning CSS to downlevel the output.

Which clients are affected

Data from caniemail.com. Range syntax support is untested on caniemail for most clients. "Unconfirmed" means the client uses a modern engine (WebKit/Gecko) that likely supports it, but there's no verified test data.

What the fix looks like

The CSS needs two transformations before it reaches email clients:

1. Convert range syntax to legacy. (width >= 40rem) becomes (min-width: 40rem)
2. Unnest media queries. Move @media from inside the selector to the top level, wrapping the selector inside instead.

The result:

/* After downleveling — works in Gmail again */
@media (min-width: 40rem) {
  .sm_bg-red-300 {
    background-color: rgb(255, 162, 162);
  }
}

References

• caniemail.com: @media support across email clients
• caniemail.com: CSS nesting support
• Google: CSS support in Gmail
• React Email #2712: Tailwind breakpoints don't work in Gmail
• PR #3086: downlevel CSS for email client compatibility
• Maizzle: Tailwind CSS framework for HTML email