Skip to main content

Troubleshooting CSS Media Queries for Mobile Email Clients

Debug CSS media query failures in Gmail, Outlook, and iOS Mail for responsive HTML email layouts on mobile devices.

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

  1. Isolate the @media block: Strip all non-essential CSS. Test with a single max-width: 600px query to verify baseline execution.
  2. Verify client support matrix: Use Litmus or Email on Acid to confirm query execution in Apple Mail and Gmail across recent client versions.
  3. 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).
  4. Validate viewport meta tags: Confirm <meta name="viewport" content="width=device-width, initial-scale=1"> is present before the </head> closing tag.
  5. 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

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.

Device widths against one breakpoint Common phone widths cluster between 320 and 430 pixels while the desktop content width sits at 600, leaving a wide gap where a single breakpoint can sit safely. One Breakpoint Fits the Whole Gap 320 375 390 430 600 breakpoint at 480px phones cluster here desktop content width
Phone widths and the desktop content width are far apart, so a single breakpoint in the gap needs no per-device tuning.

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
Survival of the embedded style block The head style block survives in Apple Mail, iOS Mail and Gmail on a Google account, is rewritten by Outlook.com, and is removed by the Gmail app on non-Google accounts. Does the Style Block Reach the Renderer? Survives intact Apple Mail, iOS Mail Gmail on a Google account Queries evaluate normally. Survives, rewritten Outlook.com web Yahoo Mail web Selectors are prefixed, so keep them simple and flat. Removed entirely Gmail app, non-Google account some Android stock clients Only inline widths remain — the fluid layer must carry it.
Design so the middle and right columns still produce a correct layout; the query is the refinement, not the foundation.

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.

Technical Validation Checklist

Media-query breakpoint behavior across clients A single max-width 600px breakpoint fires reliably in Apple Mail and iOS Mail, partially in Gmail web, is stripped in the Gmail Android app, and is ignored entirely by Outlook desktop. Does @media Fire? 600px breakpoint Apple Mail fires iOS Mail fires Gmail Web partial Gmail App stripped Outlook ignored Samsung fires inline-first base required
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.

Frequently Asked Questions

Why does my media query work in Gmail on the web but not in the app?

Because the app's behaviour depends on the account type rather than on the app. A Google account routes the message through Gmail's sanitiser, which keeps the embedded style block; a non-Google account added to the app is rendered without it. The same app, the same message, two outcomes — which is why the fluid layer has to carry the layout on its own.

Should the breakpoint be min-width or max-width?

max-width, targeting the narrow case. Email's desktop layout is a fixed 600-ish pixels rather than a fluid canvas, so there is no wide state to progressively enhance into — the sensible baseline is the desktop layout and the query narrows it. A mobile-first min-width approach inverts that and leaves the stripped-CSS clients showing the mobile layout on desktop.

Can I use more than one breakpoint?

You can, and it is rarely worth it. Email content is one column of text at a fixed maximum width, so the only genuine transition is "does this fit beside its neighbour". Additional breakpoints multiply the states to test across a client matrix that already has more variation than a website's.

Do media queries work in Outlook on Windows?

No, and that is by design in the template rather than a problem to solve: the desktop layout is what the Word engine should render, and it is the layout outside the query. Outlook mobile, which is a different engine, does honour them.

Why is !important needed inside the query?

Because the rules being overridden are inline styles, and an inline declaration beats a stylesheet rule regardless of source order. !important in the query is what lets it win. This is the one place in email where the flag is routine rather than a warning sign.

← Back to Responsive Email Layouts