Dark Mode Email: How Gmail, Apple Mail and Outlook Recolour It

On the web, browsers apply your dark mode media queries as written. In email, a client may apply them, recolour your email itself, or never read your dark-mode rules at all. This guide covers what each client does and the fixes that hold up in all three cases.

How each email client handles dark mode

Start from how your readers' clients behave. A dark theme that looks right in Apple Mail can be unreadable in Gmail Android.

Email Client	Dark mode behaviour	prefers-color-scheme	What you can do
Apple Mail (iOS & macOS)	No inversion (standards)	Works	`@media (prefers-color-scheme: dark)`
Gmail (Web / Desktop)	No inversion (keeps HTML light)	Not supported	None (renders original light styles)
Gmail (iOS)	Full recolouring	Not supported	`linear-gradient()` background
Gmail (Android)	Partial recolouring	Not supported	`linear-gradient()` background
Outlook.com / OWA	Partial colour inversion	Works	`[data-ogsc]`, `[data-ogsb]`
Outlook for Windows (Classic)	Partial inversion (Word engine)	Not supported	MSO VML conditionals

The color-scheme meta tags

The first step is telling clients that the email was designed for both light and dark mode. When WebKit-based clients (such as Apple Mail) inspect your HTML, they look for specific meta declarations.

Add both the W3C standard color-scheme meta tag and the Microsoft/Apple vendor variant inside your <head>:

meta-tags.html

61 lines

<!-- 1. Declare Dual Color Scheme Support in <head> -->
<meta name="color-scheme" content="light dark">
<meta name="supported-color-schemes" content="light dark">

<style>
  /* 2. Declare Root Variables and Opt-in Styles */
  :root {
    color-scheme: light dark;
    supported-color-schemes: light dark;
  }

  /* 3. Target WebKit & Modern Standards (Apple Mail, iOS, Thunderbird) */
  @media (prefers-color-scheme: dark) {
    .dark-bg {
      background-color: #121212 !important;
    }
    .dark-card {
      background-color: #1e1e1e !important;
      border-color: #333333 !important;
    }
    .dark-text {
      color: #f5f5f5 !important;
    }
    .dark-muted {
      color: #a0a0a0 !important;
    }
    /* Logo swap */
    .light-logo {
      display: none !important;
    }
    .dark-logo {
      display: block !important;
    }
  }

  /* 4. Target Outlook.com / OWA / Outlook Android via Data Attributes */
  [data-ogsc] .dark-bg {
    background-color: #121212 !important;
  }
  [data-ogsb] .dark-bg {
    background-color: #121212 !important;
  }
  [data-ogsc] .dark-card {
    background-color: #1e1e1e !important;
  }
  [data-ogsb] .dark-card {
    background-color: #1e1e1e !important;
  }
  [data-ogsc] .dark-text {
    color: #f5f5f5 !important;
  }
  [data-ogsc] .dark-muted {
    color: #a0a0a0 !important;
  }
  [data-ogsc] .light-logo {
    display: none !important;
  }
  [data-ogsc] .dark-logo {
    display: block !important;
  }
</style>

Why both meta tags? name="color-scheme" is the standard name that current clients read. name="supported-color-schemes" is an older name that earlier Apple Mail versions looked for, so Parcel's guide keeps it alongside. The second tag costs nothing.

Why dark mode styles need !important

In standard email development, styles are inlined into elements (e.g. style="background-color: #ffffff; color: #1a1a1a;") to survive Gmail webmail sanitization (see our deep dive on CSS inlining for email).

Because inline styles carry higher CSS specificity than class rules in a <style> block, your dark mode rules inside @media (prefers-color-scheme: dark) will fail to apply unless every property is appended with !important.

The specificity rule for dark mode email

Always inline light mode values as the baseline HTML attribute. Then use .dark-class { color: #f5f5f5 !important; } in the head stylesheet. The !important flag is the only mechanism capable of overriding the inline style declaration.

Gmail app dark mode: protect backgrounds with linear-gradient

Gmail's Android app does not apply @media (prefers-color-scheme: dark). It recolours the email itself:

It analyzes the hex color of your background and text.
If the background is light (#ffffff), it forcibly transforms it to a dark hue (#121212).
If the text is dark, it inverts it to white or light gray.
If text is already white on a dark container, it sometimes inverts the container anyway, creating unreadable gray-on-gray text.

The defence relies on one quirk: Gmail does not invert background images (Stripo documents this), and a linear-gradient() is a background image, not a background colour, so a gradient of one colour keeps that colour.

gradient-background.html

21 lines

<!-- Gmail Android dark mode: a linear-gradient background it leaves alone -->
<!-- Gmail inverts background-color, but treats linear-gradient() as an image asset -->
<table border="0" cellpadding="0" cellspacing="0" role="presentation" width="100%">
  <tr>
    <td style="
      background-color: #ffffff;
      background-image: linear-gradient(#ffffff, #ffffff);
      padding: 32px 24px;
      color: #111827;
    ">
      <!-- Even when Gmail inverts background-color to #121212, the 
           gradient stays #ffffff, preventing unexpected dark mode clobbering. -->
      <h2 style="margin: 0 0 12px 0; font-family: sans-serif; font-size: 20px; color: #111827;">
        Protected Content Block
      </h2>
      <p style="margin: 0; font-family: sans-serif; font-size: 15px; line-height: 24px; color: #4b5563;">
        This section retains pure white background even on aggressive Android client engines.
      </p>
    </td>
  </tr>
</table>

By setting linear-gradient(#ffffff, #ffffff), the gradient renders as a solid, flat white to the human eye. When Gmail runs its color-inversion pass, it mutates the background color fallback, but the gradient layer remains anchored on top, keeping your branded card or hero banner intact.

Dark mode logo: keeping it visible

One of the most common dark mode defects is the disappearing company logo. A dark charcoal or black brand logo with a transparent background renders beautifully against a white header. But the moment the client inverts the container to pitch black, the typography vanishes entirely.

Developers often attempt a dual-image toggle (showing .light-logo in light mode and .dark-logo in dark mode). That works in Apple Mail but not in Gmail Android or Outlook desktop, where both images may render or the dark logo stays hidden.

The fix that works across clients is a white drop-shadow outline:

logo-protection.html

13 lines

<!-- Logo protection: a white drop-shadow outline -->
<!-- Invisible in light mode against white, creates crisp separation in dark mode -->
<img src="https://emailens.dev/logo-dark-ink.png"
     alt="Company Logo"
     width="140"
     height="36"
     style="
       display: block;
       width: 140px;
       height: auto;
       border: 0;
       filter: drop-shadow(0 0 1px #ffffff) drop-shadow(0 0 2px #ffffff);
     " />

Light Mode Rendering

EMAILENS LOGO

Glow blends invisibly into white background

Dark Mode Inversion

EMAILENS LOGO

Crisp white contour preserves legibility

Where filter works: filter works in Apple Mail. filter is not supported in Gmail. filter is not supported in Outlook Classic. To reach every client:

CSS outline: Declare the inline filter: drop-shadow(...) style for Apple Mail and modern mobile clients.
Outline baked into the PNG: In Figma or Photoshop, export your dark logo with a subtle 1px to 2px semi-transparent white outer glow or stroke directly into the raster alpha channel. It is invisible on light backgrounds and visible in Gmail Android and Outlook desktop.
Logo on its own background: Alternatively, enclose the logo inside a dedicated table cell with an explicit background color (e.g. bgcolor="#f4f4f5") and rounded corners, ensuring the logo always sits on a predictable ground.

Dark mode email signatures

A signature is a small HTML email of its own, and it breaks in dark mode the same way: a black logo on a transparent PNG disappears, and text set to a fixed dark grey can end up dark on a dark background. You also have less control than in a campaign, because the signature is pasted into whatever client the sender uses and has no <style> block of its own, so the prefers-color-scheme overrides above are not available.

Give the logo its own ground. Export it on a solid white or light rounded tile instead of a transparent background, or add the light outline described above, so it reads whichever way the client recolours it.
Leave text colour alone. Text with no colour set follows the client's light or dark theme. A hard-coded near-black is what clients have to guess about.
Avoid a background colour on the whole signature. A white panel stays white in some clients and turns dark in others, and either way it no longer matches the email around it.
Check it in both modes before rolling it out to a team: paste it into an email and preview it with the dark mode preview tool.

Outlook.com and Outlook on the web in dark mode

@media prefers-color-scheme works in Outlook 365. When a reader switches Outlook on the web into dark mode, it recolours the email and marks the elements it changed with [data-ogsc] and [data-ogsb]; repeating your dark colours on those attributes, as in the snippet above, makes it use yours. The selector syntax and the other client hooks are in email client targeting CSS, and Outlook's wider CSS support in the Outlook CSS guide.

Partial dark mode coverage: white text on a white card

The most destructive dark mode defect is usually not a lack of dark mode styles, it is partial dark mode coverage.

Consider what happens when a template defines background-color: #121212 !important on the outer body container, but an inner content card specifies bgcolor="#ffffff" or inline style="background:#ffffff;" that the dark mode stylesheet forgets to target. On Apple Mail:

The outer frame turns pitch black (#121212).
The typography classes turn white (color: #ffffff !important) due to the global dark styles.
The inner card cell remains stark white (#ffffff) because no rule overrode its inline background.
The result: invisible white text on a white card, surrounded by an ink-black void.

To prevent it, keep the class pairings symmetrical: every element that sets an inline light background or text color must possess a matching class (.dark-bg, .dark-card, .dark-text) in your dark mode stylesheet.

Watch your payload budget: declaring verbose dark mode media queries and duplicate [data-ogsc] rules across dozens of elements adds markup weight. Ensure your final sanitized HTML stays comfortably under the 102KB threshold (see our breakdown on why Gmail clips emails at 102KB).

What to check in dark mode before you send

The dark mode items to verify before a campaign or transactional template ships. The full pre-send checklist is in how to test HTML emails.

Meta tags present: Both color-scheme and supported-color-schemes are declared in the <head>.

!important on every override: Every CSS property inside @media (prefers-color-scheme: dark) has !important to override inline attributes.

Outlook web fallbacks: Duplicate [data-ogsc] and [data-ogsb] selectors exist for every dark mode class.

Logos and icons protected: Dark transparent logos have white drop-shadows or translucent backing badges.

Sufficient contrast: Text colors against inverted backgrounds meet WCAG AA (minimum 4.5:1 contrast ratio). Use light gray (#e5e5e5) rather than pure harsh white (#ffffff).

Tested in real clients: Validated across both WebKit (Apple Mail) and forced-inversion engines (Gmail Android).

Questions

Why does Gmail on Android invert email colors even with @media (prefers-color-scheme: dark)?

@media prefers-color-scheme is not supported in Gmail Android. Instead the app recolours light backgrounds and dark text itself, based on their luminance. You can defend against this with CSS linear gradients, which Gmail treats as images and leaves alone.

Why are my dark mode styles not applying?

Usually because the light colours are inline. Inline styles beat class rules in a <style> block, so every declaration inside @media (prefers-color-scheme: dark) needs !important to override them. A client that does not read prefers-color-scheme ignores the rules whatever their specificity, and recolours the email itself.

How do I prevent dark logos and icons from vanishing in dark mode?

Transparent PNG logos with black or dark lettering disappear when the client inverts the background to black. The most reliable production fix is adding a 1px to 2px semi-transparent white outer glow or drop shadow (e.g., filter: drop-shadow(0 0 1px #ffffff) drop-shadow(0 0 2px #ffffff);) directly in CSS or baked into the PNG asset itself. In light mode the outline is invisible against white backgrounds, but in dark mode it creates an instant, crisp boundary.