CSS Media Queries for Mobile Email Clients

When deploying transactional templates at scale, inconsistent rendering across mobile platforms is a deterministic failure mode. The core challenge lies in how modern email clients parse and execute CSS media queries. This guide isolates exact failure points for @media queries and provides a production-ready debugging workflow consistent with Mastering Email HTML & CSS standards.

The Client-Side Query Stripping Mechanism

Gmail's web and mobile clients aggressively strip <style> blocks containing unsupported selectors, malformed syntax, or excessive specificity. iOS Mail respects @media but applies aggressive viewport scaling that breaks fixed-width fallbacks. To maintain structural integrity, implement progressive enhancement patterns rather than relying on blanket responsive rules. Understanding these constraints is foundational when architecting Responsive Email Layouts that survive automated inline processing pipelines.

Stripping Triggers to Avoid:

@media rules nested inside unsupported @supports or @keyframes blocks
Pseudo-classes (:hover, :active, :focus) inside mobile breakpoints (Gmail strips these)
Unescaped special characters in media query conditions
<style> tags placed outside <head> or duplicated in <body> (behavior is client-dependent)

Exact Troubleshooting Workflow for Transactional Payloads

Isolate the @media block: Strip all non-essential CSS. Test with a single max-width: 600px query to verify baseline execution.
Verify client support matrix: Use Litmus or Email on Acid to confirm query execution in Apple Mail and Gmail across recent client versions.
Check inline CSS automation: Ensure your build pipeline does not strip <style> tags prematurely. Transactional systems often use MJML or custom Node.js parsers that require explicit configuration to preserve media queries (preserveMediaQueries: true in Juice).
Validate viewport meta tags: Confirm <meta name="viewport" content="width=device-width, initial-scale=1"> is present before the </head> closing tag.
Debug with browser dev tools: Use Safari's Web Inspector for iOS Mail simulation and Chrome DevTools for Gmail's DOM stripping behavior.

Production-Ready Syntax & Pipeline Config

Baseline Mobile Query (Safe for Gmail/iOS):

@media only screen and (max-width: 600px) {
  .wrapper { width: 100% !important; }
  .mobile-hide { display: none !important; }
  .mobile-stack { display: block !important; width: 100% !important; }
}

Node.js Inliner Configuration (Juice):

const juice = require('juice');
const fs = require('fs');

const html = fs.readFileSync('./templates/email.html', 'utf8');

const config = {
  preserveMediaQueries: true,
  preserveFontFaces: true,
  removeStyleTags: false, // Critical: keeps <style> in <head> for clients that support it
};

const inlined = juice(html, config);
fs.writeFileSync('./dist/email.html', inlined);

Viewport Meta Injection (Must be exact):

<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <style>/* media queries here */</style>
</head>

Configuration Fixes for Persistent Failures

If queries are consistently stripped, implement a hybrid approach using table-based fluid layouts with max-width constraints. For iOS Mail zoom issues, force -webkit-text-size-adjust: 100% and apply !important declarations to critical mobile breakpoints. Always test with actual device emulators rather than relying solely on desktop previews. Transactional emails require pixel-perfect reliability, making systematic query validation non-negotiable.

iOS Text Zoom Fix:

@media only screen and (max-width: 600px) {
  body, table, td, p, a, li, blockquote {
    -webkit-text-size-adjust: 100% !important;
    -ms-text-size-adjust: 100% !important;
  }
}

Gmail App Fallback Strategy:
Gmail App ignores <style> in <head> on some Android versions. Use inline style attributes for critical layout properties, and reserve @media for non-structural enhancements (padding, font-size, visibility toggles). For the exact reproduction steps and the inline-first fallback markup, see fixing Gmail app media query stripping.

Pipeline Verification:

# Validate HTML structure before deployment
npx html-validate transactional-template.html

# Check that @media rules survive the inlining step
grep -c "@media" dist/emails/*.html
# Compare the count against your source templates to confirm no rules were stripped

Technical Validation Checklist

Verify @media query syntax uses only screen and prefix for maximum parser compatibility
Confirm no unsupported pseudo-classes (:hover, :focus, :nth-child) inside mobile queries
Ensure inline CSS inliner is configured with preserveMediaQueries: true and removeStyleTags: false
Test against Gmail App (Android/iOS), Apple Mail, and Samsung Email using real devices or Litmus
Validate HTML structure passes W3C validator with email-specific allowances (allow bgcolor, align, valign on tables)
Audit transactional API payload for premature CSS minification or whitespace stripping before SMTP dispatch

The same max-width breakpoint fires in Apple Mail, iOS Mail and Samsung, runs partially in Gmail web, and is stripped or ignored in the Gmail Android app and Outlook desktop.

Breakpoint Strategy: One Breakpoint, Chosen Deliberately

Email is not the web — you do not get a fluid range of devices with reliable viewport reporting, you get a handful of clients that either honor a breakpoint or do not. The practical consequence is that a single max-width: 600px breakpoint covers almost every real-world case, and stacking three or four breakpoints adds parse surface (more chances for Gmail to reject the block) without adding coverage.

Pick 600px because it is the de-facto email content width and because the clients that honor @media at all — Apple Mail, iOS Mail, Samsung Email — all report a device width below it on phones. The clients that do not honor it — Gmail App, Outlook desktop — will not be saved by a second breakpoint either, so the answer for them is the inline-first base, not more queries.

/* One deliberate breakpoint. Apple Mail, iOS Mail, Samsung Email honor it;
   Gmail App and Outlook desktop ignore it and fall back to the inline base. */
@media only screen and (max-width: 600px) {
  .container { width: 100% !important; }
  .col       { display: block !important; width: 100% !important; }
  .pad       { padding: 16px !important; }     /* tighten desktop padding on mobile */
  .h1        { font-size: 24px !important; }    /* scale headline down on small screens */
}

If you genuinely need a second tier (tablet vs phone), use min-width/max-width ranges, not overlapping max-width rules, so the cascade is unambiguous. But validate the extra block actually fires before shipping it — every additional rule is another chance for Gmail web's parser to discard the whole <style>.

The Fluid-Plus-Media-Query Hybrid

The most resilient responsive pattern does not rely on @media at all for the baseline — it builds a layout that already degrades gracefully using fluid widths and max-width, then layers media queries on top as enhancement. This is the only pattern that holds up in Gmail App and Outlook desktop, because the fluid base does the work the stripped/ignored query cannot.

<!-- Fluid base: width:100% + max-width caps the column on desktop, fills on mobile,
     and needs NO @media to do it. Outlook ignores max-width on <div>, so the cap
     lives on a <table> width attribute it honors. -->
<table role="presentation" width="100%" cellpadding="0" cellspacing="0">
  <tr>
    <td align="center">
      <!--[if mso]><table role="presentation" width="600"><tr><td><![endif]-->
      <table role="presentation" width="100%" style="max-width:600px;" cellpadding="0" cellspacing="0">
        <tr>
          <!-- Two columns that already wrap because each is width:100% on a narrow
               viewport via align="left" + inline-block fallback. Gmail App (no @media)
               still gets a usable single column from the fluid base. -->
          <td class="col" width="50%" style="display:inline-block;width:100%;max-width:300px;vertical-align:top;">A</td>
          <td class="col" width="50%" style="display:inline-block;width:100%;max-width:300px;vertical-align:top;">B</td>
        </tr>
      </table>
      <!--[if mso]></td></tr></table><![endif]-->
    </td>
  </tr>
</table>

/* Enhancement layer only: clients that honor @media get tighter control.
   Clients that strip it (Gmail App) already have a working fluid layout. */
@media only screen and (max-width: 600px) {
  .col { display: block !important; width: 100% !important; max-width: 100% !important; }
}

The discipline here is that nothing layout-critical lives only inside the @media block. The query refines; it never rescues. If you delete the query entirely, the email must still be readable — that is the test for whether your hybrid is correct. Keeping that inline base intact through the build is exactly what the CSS inliner pipeline must guarantee.

Per-Client Media-Query Support, in Detail

Client	`@media max-width`	`prefers-color-scheme`	Head `<style>` retained	Practical guidance
Apple Mail (macOS)	Fires	Fires	Yes, full	Author freely; this is your reference client
iOS Mail	Fires	Fires	Yes, full	Add `-webkit-text-size-adjust:100%` to stop auto-zoom
Gmail Web	Fires (if `<style>` valid)	Fires	Yes, one well-formed block	A single parse error kills the entire block
Gmail App (Android)	Stripped on many builds	Stripped	No	Inline-first base mandatory; treat `@media` as absent
Gmail App (iOS)	Inconsistent	Inconsistent	No on many builds	Same as Android — do not depend on the query
Outlook 2016/2019/365 (Win)	Ignored (Word engine)	Ignored	N/A	Use `mso-` conditionals + fixed `<table width>`
Outlook macOS	Fires (WebKit)	Fires	Yes	Behaves like Apple Mail
Samsung Email	Fires	Fires (forces dark aggressively)	Yes	Test dark-mode color forcing explicitly

The split this table reveals is the whole game: the WebKit-based clients (Apple Mail, iOS Mail, Outlook macOS, Samsung) honor everything; Gmail web honors it if the CSS is clean; Gmail App and Outlook desktop ignore it and demand a working inline base. Outlook desktop's @media blindness is handled separately in the Outlook rendering fixes reference.

Variant Cases

Case: query fires in Litmus but not on a real Gmail App install. Litmus's Gmail App screenshots can use a rendering path that differs from a live Android device. When the breakpoint passes in Litmus but real users report a desktop layout, trust the device — your @media is being stripped on real Gmail App builds. Move the layout-critical declarations to the inline base; the full reproduction and recovery is in fixing Gmail app media query stripping.

Case: the breakpoint fires but inline styles win. After automated CSS inlining, every element carries a high-specificity style attribute. A .col { width:100% } inside the query loses to the inlined width:300px. The fix is !important on every override inside the @media block so it beats the inline attribute — already shown in the snippets above.

Case: iOS Mail scales the whole email up. iOS Mail auto-scales fixed-width emails wider than the viewport. Set the viewport meta exactly, add -webkit-text-size-adjust:100% inside the mobile query, and ensure the outer table uses width:100% with a max-width cap rather than a hard pixel width.

Validation Checklist

Exactly one deliberate max-width: 600px breakpoint (or unambiguous ranges, validated to fire)
Layout is readable with the entire @media block deleted (fluid base proves itself)
Every override inside the query carries !important to beat inlined style attributes
Tested on a real Gmail App install, not only Litmus screenshots
-webkit-text-size-adjust:100% present to stop iOS Mail auto-zoom
Outlook desktop gets a fixed <table width> base, not a @media-dependent layout
@media count in dist/ matches source after the inline step

Fixing Gmail App Media Query Stripping — the inline-first recovery for Android Gmail
Responsive Email Layouts — the broader fluid and hybrid architecture
Outlook Rendering Fixes — MSO conditionals for the client that ignores @media
Inline CSS Automation — keep @media rules alive through the inliner

← Back to Responsive Email Layouts