How dark mode actually behaves, client by client:
Over 25% of email opens now happen in dark mode, per Litmus’s Email Client Market Share report (May 2026). Design for only one of the three behaviors above and the other two will render your email wrong, sometimes badly enough to make it unreadable.
This post covers the specific CSS techniques for controlling dark mode across clients: the color-scheme meta tag, the prefers-color-scheme media query, Outlook.com’s proprietary attribute selectors, and how to keep logos and images legible when a client inverts colors underneath them. For the broader design picture (layout, hierarchy, accessibility), see Email Design Best Practices, which covers dark mode at a summary level; this post goes deeper into the mechanics.
How Different Email Clients Handle Dark Mode
Dark mode support splits into three distinct behaviors, and confusing them is the most common source of broken emails.
| Behavior | What happens | Clients |
|---|---|---|
| No automatic change | Email renders exactly as coded; nothing shifts unless you add dark mode CSS | Apple Mail (macOS, iOS), Gmail desktop webmail |
| Partial inversion | Only pure black and pure white values flip; other explicit colors are left alone | Outlook.com (webmail), Outlook app (iOS, Android) |
| Full inversion | Colors are rewritten throughout the message, including over backgrounds and images, without a contrast check | Gmail app (iOS) |
Apple Mail does not automatically invert colors in dark mode. According to Campaign Monitor’s dark mode guide, Apple Mail is a “no change” client, meaning developers who want dark-mode-specific styling have to opt in with @media (prefers-color-scheme: dark). Outlook.com behaves differently: “white and black are inverted” while “text over background colors are not affected,” so an explicit #f4f4f4 background stays put but a hardcoded #ffffff will flip. Gmail’s iOS app is the most aggressive of the three, altering colors throughout the email and, per the same guidance, not verifying contrast on the result, which is why text can end up nearly invisible against its own background after Gmail is done with it.
Meta Tags and Media Queries: Opting Into Dark Mode Styling
Two mechanisms let you control dark mode explicitly instead of leaving it to each client’s default behavior: the color-scheme meta tag and the prefers-color-scheme media query.
<meta name="color-scheme" content="light dark">
<meta name="supported-color-schemes" content="light dark">This tells clients that support it your email is built for both schemes, which is a prerequisite for prefers-color-scheme to activate reliably in some clients. Support is uneven: per caniemail.com, @media (prefers-color-scheme: dark) is supported in Apple Mail (macOS 10.3+, iOS 12.2+), Gmail (desktop webmail, iOS, Android, and mobile webmail since early 2020), and Outlook (Windows 2013+, macOS 2019+, Outlook.com since July 2019, iOS and Android since 2020), but not in Yahoo Mail.
@media (prefers-color-scheme: dark) {
body, .email-bg { background-color: #1a1a1a !important; }
.email-text { color: #e8e8e8 !important; }
.email-link { color: #4da6ff !important; }
}Put !important on every property here. Email clients apply inline styles by default, and the media query only wins the specificity fight if it overrides them explicitly. If you’re building a responsive HTML email template, this block sits in the same <style> tag as your existing breakpoint media queries, it does not need its own separate stylesheet.
Reaching Outlook.com With data-ogsc and data-ogsb
Outlook.com doesn’t rely on prefers-color-scheme alone. When it inverts a color, it tags the affected element with custom data attributes so you can target the result directly. As documented by Rémi Parmentier, Outlook.com adds data-ogsc (original style color) and data-ogsb (original style background) to elements whose color it changes, and you can use attribute selectors to react to that change.
Outlook.com only recognizes an attribute selector on its own ([attr]) or paired directly with an element selector (E[attr]), not chained with a class like .email-bg[data-ogsb]. The workaround is to put the attribute on a parent element and target children through it:
[data-ogsc] .email-text { color: #e8e8e8 !important; }
[data-ogsb] .email-bg { background-color: #1a1a1a !important; }Because Outlook.com applies this logic in the browser rather than through a media query, duplicating your prefers-color-scheme rules with [data-ogsc] and [data-ogsb] prefixes is the only way to reach it specifically. This same attribute pair also works for swapping images on Outlook.com, which matters for the logo problem below.
Designing Logos and Images That Survive Inversion
A transparent PNG logo with dark text or dark linework is the single most common dark-mode casualty. On a client that inverts a white page background to near-black, a transparent logo built to sit on white effectively loses its background, and dark linework disappears into the new dark canvas around it.
Email on Acid’s guide to dark mode logo problems recommends either adding a light stroke, shadow, or glow around dark linework so it stays visible against a dark canvas, or swapping in a dedicated dark mode version of the logo entirely. The swap uses the same prefers-color-scheme media query, toggling display on two stacked images:
@media (prefers-color-scheme: dark) {
.dark-mode-hide { display: none !important; }
.dark-mode-show { display: block !important; }
}<img src="logo-light.png" class="dark-mode-hide" alt="Company logo">
<!--[if !mso]><!-->
<img src="logo-dark.png" style="display:none;" class="dark-mode-show" alt="Company logo">
<!--<![endif]-->This technique depends on prefers-color-scheme support, so it reaches Apple Mail and Outlook for Mac reliably but not every Outlook or Gmail version, per the same guide. For clients it doesn’t reach, a stroke or glow on the logo itself is the more defensive fallback since it works regardless of whether the image-swap media query fires.
Why Pure Black and Pure White Backgrounds Break
Pure black (#000000) and pure white (#FFFFFF) are exactly the values that trigger Outlook.com’s partial inversion, since it targets those two hex codes specifically rather than reacting to lightness in general. Litmus’s dark mode guide recommends substituting near-black and near-white values, such as #0E0E0E and #FEFEFE, which read as identical to pure black and white in light mode but sidestep the hardcoded inversion trigger in clients that flip on exact values.
As covered in Email Layout, setting an explicit background color on every section’s table cell, not just the outer wrapper, is also structural insurance here: if only the outer <body> has a background and a client inverts it, inner cells with no background of their own can end up transparent over a canvas that’s now the wrong color underneath them.
Testing Dark Mode Before You Send
None of this is safe to assume from reading the spec. Client behavior changes between app versions, and the categorization in the table above reflects current documented behavior, not a permanent contract.
Preview your rendered HTML in Litmus or Email on Acid, both of which include dedicated dark mode previews across the major clients, before sending to any list with meaningful iOS or Outlook.com traffic. At minimum, manually check Apple Mail (iOS and macOS), Gmail’s iOS app, and Outlook.com, since those three cover the three behaviors in the table above. Once your dark mode styles pass client testing, How to Send HTML Email the Right Way covers the MIME structure and delivery steps for getting the finished template into the inbox.
Whether you hand-code these media queries or build the template in Coldletter’s visual editor, the underlying HTML is the same either way, so verify the rendered output in an actual client preview before you rely on it going out to your full list.
Frequently Asked Questions
Does Gmail support dark mode for HTML emails?
It depends on which Gmail. Gmail’s desktop webmail does not automatically change email content colors in dark mode. Gmail’s iOS app does, rewriting colors throughout the message without checking the resulting contrast, which can produce hard-to-read combinations the sender never intended.
Why didn’t my email change at all in Apple Mail’s dark mode?
That’s expected default behavior, not a bug. Apple Mail does not automatically invert or adjust email colors when the device switches to dark mode. To get dark-mode-specific styling in Apple Mail, you have to add it explicitly with @media (prefers-color-scheme: dark) CSS in your email’s <head>.
What does the color-scheme meta tag do in email?
<meta name="color-scheme" content="light dark"> tells a supporting client that your email is designed for both light and dark schemes, which helps prefers-color-scheme media queries activate reliably. Support is limited to a subset of clients, including Apple Mail and recent Outlook and Gmail versions, so pair it with the CSS media query rather than relying on the meta tag alone.
Why does my transparent PNG logo disappear in dark mode?
A transparent logo with dark text or linework is built to sit on a light background. When a client inverts that background to near-black, the logo loses its visual foundation and dark elements blend into the new dark canvas. Add a light stroke or glow around the dark elements, or swap in a dedicated dark mode version of the logo using a prefers-color-scheme image swap.
Should I avoid pure black and white backgrounds in my email HTML?
Yes, when practical. Pure #000000 and #FFFFFF are the exact values that trigger hardcoded inversion in clients like Outlook.com, which target those hex codes specifically. Near-black and near-white substitutes such as #0E0E0E and #FEFEFE look identical in light mode and avoid the forced flip.
How do I test dark mode rendering before sending a campaign?
Use a preview tool like Litmus or Email on Acid, both of which render your HTML across the major clients in both light and dark mode. At minimum, manually verify Apple Mail (iOS and macOS), Gmail’s iOS app, and Outlook.com, since those three clients represent the three distinct dark mode behaviors covered in this guide.
I’ve spent my career building software at scale with a soft spot for email: deliverability, lifecycle campaigns, and getting messages to actually land. I started Coldletter to fix what bugged me about transactional and marketing email tools. I’m based in Vancouver.