1. Three things a client can do to your colours
When a reader turns on dark mode, their mail client has to decide what to do with an email that was designed on white. There is no standard for it. Each client makes its own call, and in practice they fall into three behaviours:
- No change. The client darkens its own interface — the inbox list, the toolbar — and shows your email exactly as coded. A white email stays white, like a lit window in a dark room. If you wrote dark-mode CSS, a client in this group may apply it; if you did not, nothing happens.
- Partial invert. The client looks for light backgrounds and darkens them, and for dark text and lightens it. Anything that is already dark — a navy header, a black footer — is left as it is. This is the most common version of “the inbox redesigned my email”.
- Full invert. The client recolours everything, dark areas included. A deliberately dark hero can come back light, and a brand colour you chose carefully can come back as one you never picked.
The important word is without. In the last two groups the client is not reading your design intent. It is running a rule over your colour values, and your CSS is input to that rule rather than instructions to it.
2. Which client does what
Clients change this behaviour in app updates, often without saying so. Treat the table below as the typical picture at the time of writing, drawn from behaviour that published email-testing guides have documented consistently — not as a contract. Where the behaviour depends on the app or version, the row says so.
| Client | Typical behaviour | Reads your dark CSS | What to know |
|---|---|---|---|
| Apple Mail (Mac, iPhone, iPad) | No change to a designed email | Yes | Applies your dark styles when you declare support with the color-scheme meta. An email with no background colours of its own may be darkened for you. |
| Gmail in a desktop browser | No change | No | Dark theme darkens Gmail’s interface around the message, not the message. |
| Gmail apps (Android, iOS) | Partial or full invert | No | Recolours on its own, with no hook you can target. Widely reported as the most aggressive of the big clients. |
| Outlook.com in a browser | Partial invert | No | Marks each element it recolours with data-ogsc / data-ogsb — the one hook you get. |
| Outlook apps (iOS, Android) | Partial or full | Varies | Depends on the app and its version. Test the one your list actually uses. |
| Classic Outlook for Windows (Word engine) | Full invert when dark mode is on | No | Reads no @media block at all, so a dark-mode query never reaches it. |
Two things follow from the table. First, of the clients above only Apple Mail reliably applies your own dark-mode CSS, so dark CSS is an improvement for some readers, not a plan for all of them. Second, every client that recolours on its own is looking at the same two things: how light your backgrounds are, and how dark your text is. That is why the colour choices in section 5 matter more than any media query.
3. The code that gives you a say
There are three pieces, and each one reaches a different set of clients.
The color-scheme declaration. A meta tag in the <head> tells clients that support it that your email has been designed for dark as well as light. Declare it under both names — the standard color-scheme and the older supported-color-schemes that Apple’s engine used — and repeat it as a CSS property on :root.
The media query. @media (prefers-color-scheme: dark) holds your dark styles. One catch trips almost everyone: email CSS is inlined, and an inline style attribute beats any rule in a <style> block. Every dark override therefore needs !important, or the inline light colour wins and nothing changes.
The Outlook.com attributes. Outlook.com does not read the media query, but when it recolours an element it adds data-ogsc (it changed the text colour) or data-ogsb (it changed the background). Those attributes only exist in its dark view, so you can use them as selectors to replace its guesses with your own dark colours.
<!-- in the <head> --> <meta name="color-scheme" content="light dark"> <meta name="supported-color-schemes" content="light dark"> <style> :root { color-scheme: light dark; supported-color-schemes: light dark; } /* Apple Mail and the other clients that read it */ @media (prefers-color-scheme: dark) { .body-bg { background-color: #121417 !important; } .headline { color: #f1f1f1 !important; } .on-light { display: none !important; } .on-dark { display: block !important; max-height: none !important; } } /* Outlook.com: re-assert the same choices on the elements it recoloured */ [data-ogsb] .body-bg { background-color: #121417 !important; } [data-ogsc] .headline { color: #f1f1f1 !important; } </style>
The .on-light / .on-dark pair is the logo swap in section 4. Every override carries !important because the light colours it replaces are inline.
Gmail is missing from all of this. The <style> block survives in Gmail, but the media query never matches and there is no attribute to hook. For the Gmail apps — which recolour on their own — the only lever you have is the colours you pick in the first place.
4. Logos and images: the part nobody recolours
A dark-mode swap changes CSS and HTML colour values. An image is pixels, and clients leave pixels alone. That one fact causes most dark-mode bug reports:
- The vanishing logo. A dark logo saved as a transparent PNG was sitting on your white header. Dark mode turns the header near-black and leaves the logo dark. It disappears, and it does so at the top of the email, where everyone looks first.
- The white box. A product shot or illustration exported as a JPG with a white background becomes a bright rectangle on a dark page. It looked seamless on white because it was the same white.
- Text inside images keeps its colours exactly. That gives you control, but it fails every reader with images off — see the accessibility article on why live text matters.
The fixes, in order of how widely they work:
- Give the artwork its own edge. Add a thin light stroke or a soft light glow around a dark logo inside the PNG. On white it is invisible; on near-black it gives the mark an outline. This works in every client, because it never relies on the client doing anything.
- Bake in a background. Put the logo on a solid shape that is part of the image — a white rounded rectangle, or a block of brand colour. It reads as a badge in both modes. Our Email QA tool gives the same advice when it finds no dark-mode handling: give logos and icons a solid background so they do not vanish.
- Swap the logo for clients that listen. Code a second, light version of the logo hidden by default and show it inside
prefers-color-scheme, as in the code above. Wrap the hidden copy in<!--[if !mso]><!-->so classic Outlook does not show both. Gmail will always show the default, so the default still needs fix 1 or 2. - Export cut-outs, not white boxes. A product on a transparent PNG survives a dark background as long as the product itself has enough contrast with it. Check the edges: a light halo left over from a white-background cut-out shows up clearly on dark.
5. Pure white, pure black and the middle
Swap rules work on lightness. Pure white backgrounds and pure black text sit at the two ends of the scale, so they are the colours any swap is most certain to change. In the rules our preview uses (section 6), #ffffff becomes #1a1a1a and black text #000000 becomes #f0f0f0.
You will read advice to use #fefefe instead of white, or #010101 instead of black, to slip past the swap. Treat that as folklore. A rule based on lightness sees #fefefe and #ffffff as the same colour, and our simulator swaps both. Some developers report particular clients behaving differently at particular times, but it is not something to build a send on.
The real risk is the middle of the range, which is where brand colours live. A partial swap darkens light backgrounds and lightens dark text, and leaves mid-tones exactly as coded. That is fine for a mid-tone button, where the fill and its white label both stay put. It is not fine for mid-tone text, because the background under it moves and the text does not:
| Element | Light, as coded | After the swap | Contrast |
|---|---|---|---|
| Body text | #000000 on #ffffff | #f0f0f0 on #1a1a1a | 21:1 → 15.27:1 Fine |
| Brand-blue link | #1159da on #ffffff | #1159da on #1a1a1a | 6.06:1 → 2.87:1 Fails AA |
| Grey caption on a grey card | #666666 on #e0e0e0 | #666666 on #212121 | 4.35:1 → 2.80:1 Fails AA |
The blue link is the one to remember: comfortably above the 4.5:1 body-text threshold on white, well under it on dark, and no client recoloured it. The email accessibility article works through the contrast formula behind those ratios. The practical fix is to give links and small mid-tone text a dark-mode colour in your media query and under [data-ogsc] — and, for Gmail, to pick mid-tones that hold at least 4.5:1 against both white and near-black, which usually means slightly lighter blues than the brand guide asks for.
One more casualty of the swap is the subtle tint. A white page with an off-white panel — #ffffff and #f7f8fa — becomes #1a1a1a and #181a1e. The difference you could see in light mode is gone. If a section boundary matters, mark it with spacing or a rule, not a three-percent tint.
6. What our dark preview does — exactly
Email Preview has a Light/Dark switch that sits on top of whichever client view you are on — Browser, Gmail or Outlook — and combines with Images on/off. The order is fixed: the client view decides which CSS survives, the dark pass recolours what that client would show, and images-off replaces what is left. The view is tagged SIMULATED, and lists the number of colours it changed. These are its rules, read off the engine:
| What it reads | What happens |
|---|---|
background-color, a plain-colour background, the bgcolor attribute | Lightness above 72% → darkened to 9–17%, with saturation halved |
color | Lightness below 34% → lightened to 86–94% |
| Any colour between those thresholds | Left exactly as coded |
| Background images, gradients, CSS variables | Left as coded — only plain colour values are recoloured |
Every <img> | Never touched |
A <body> with no background or text colour of its own | Given a dark canvas, #1e1f23, and light text, #e8eaed |
!important on a swapped value | Kept on the new value |
That is a model of a partial invert, built on Outlook.com’s colour swap, and the tool tells you so on screen: Gmail’s Android inversion is more aggressive and Apple Mail respects your CSS, and no single preview can be all three. It shows the common case, not every case.
It also does not show your own dark-mode CSS, on purpose. If your HTML has a prefers-color-scheme block, the tool notes that it was not applied: this view is the forced swap a client does when it ignores your styles. That is the version of your email you have the least control over, which is why it is the one worth previewing. To check your own dark styles, open the email in Apple Mail.
Because the dark switch combines with the others, you can look at Phone · Gmail · Dark with images off in one view. And when a client comments on a shared link, the comment remembers that view and reopens it when clicked.
The Light/Dark switch in Email Preview is free to use, and previewing runs in your browser; share links need a free account. In our Email QA tool the same swap appears as a Dark mode tab, and that tab is PRO — as is the result of Email QA’s dark-mode check, which looks for a color-scheme meta or property, a prefers-color-scheme query or a [data-ogsc] rule.
7. The pre-send checklist
- Declare it.
color-schemeandsupported-color-schemesmetas set tolight dark, plus the same on:root. - Override with
!importantinside@media (prefers-color-scheme: dark)— inline styles beat it otherwise. - Repeat the important overrides under
[data-ogsc]and[data-ogsb]for Outlook.com. - No bare dark logo on a transparent PNG. Add a light edge or a baked-in background, then add the swap for clients that read it.
- No white-box JPGs on a white section. Use transparent cut-outs and check their edges on dark.
- Check mid-tone text and links against near-black. Nothing recolours them; aim for 4.5:1 on both white and dark.
- Check every button as a pair. A light button with a dark label swaps together; a mid-tone button stays together. A light button with a mid-tone label does not — the fill goes dark, the label stays.
- Don’t separate sections with a faint tint alone. Use spacing or a rule.
- Preview the forced swap, then test the real thing. Look at the worst case first, check your own dark CSS in Apple Mail, and send a seed test to the clients your list actually uses.
Drop your HTML and switch it to dark.
Email Preview shows your email on desktop and phone, in Gmail and Outlook views, in dark mode and with images off — one click each, and they combine. The views are rule-based simulations with a list of every change, not real screenshots.
The dark view is a simulation: your HTML re-coloured by the rules in section 6, modelled on one client’s partial swap. It is not a screenshot from Gmail, Outlook or Apple Mail, and it does not model the Gmail apps’ stronger inversion. The client behaviour in section 2 is the typical picture at the time of writing, and clients change it without notice. For true renders across real inboxes, that is what Litmus and Email on Acid are for — we say the same on our comparison page.
Most creative processing happens locally in your browser. Files are uploaded only when you explicitly use sharing, transfer or team features, or save to your account.
Frequently asked questions
What does dark mode do to an HTML email?
Does Gmail support prefers-color-scheme?
@media (prefers-color-scheme: dark). Gmail in a browser typically leaves the message colours alone; the Gmail apps recolour it themselves, with no CSS hook you can target. For Gmail, the only lever you have is the colours you choose in the first place.What are data-ogsc and data-ogsb?
data-ogsc on elements whose text colour it changed and data-ogsb on elements whose background it changed. Because they only exist in that dark view, you can use them as selectors — [data-ogsc] .headline { color:#f1f1f1 !important; } — to put back the dark-mode colours you chose instead of the ones Outlook.com guessed.Why does my logo disappear in dark mode?
prefers-color-scheme.Should I avoid pure white and pure black in email?
#ffffff for #fefefe is not a reliable way to stop it. A swap that works on lightness treats the two the same. The bigger risk is the middle of the range: mid-tone text and links are usually left exactly as coded while the background under them goes dark, and that is where contrast fails.Is the dark-mode preview a real screenshot, and is it free?
Find the vanishing logo before the send.
Preview your email in dark mode, in Gmail and Outlook views, on desktop and phone — free, in your browser — then run the code checks in Email QA.