Dark mode used to be a niche preference. Now it ships turned on by default for plenty of people, across iOS, Android, Windows, and macOS.
That creates a problem you don’t control. Your recipient’s email client may redraw your email’s colors before they ever see it. Some clients leave your design alone. Others invert it completely.
This guide covers how each major client treats dark mode. Then it covers the CSS that gives you control, and how to test the result. There’s a copy-paste template too.
- What Dark Mode Does to Your Email
- How Each Email Client Handles Dark Mode
- Why Emails Break in Dark Mode
- How to Code for Dark Mode
- A Dark-Mode-Safe Email Template
- Design Best Practices for Dark Mode
- Logos, Images, and Email Signatures
- Troubleshooting: Why Is My Email Still White?
- How to Test Your Emails in Dark Mode
- Make Sure Your Emails Actually Arrive
- Frequently Asked Questions About Dark Mode Emails
What Dark Mode Does to Your Email
In light mode you get dark text on a light background. Dark mode flips that, so you get light text on a dark surface.
For a web page, the site decides. Email is different. The email client decides, and it may rewrite your colors on the way to the inbox.
That’s the part most guides skip. Dark mode isn’t one behavior. It’s three, and which one you get depends on the recipient’s app.
What’s So Great About Dark Mode?
People who use dark mode tend to feel strongly about it. A few reasons it caught on:
- Easier on the eyes. Many people find it reduces strain in low light.
- Battery savings. On OLED and AMOLED screens, dark pixels draw less power.
- Readability. Some users with visual impairments find light-on-dark easier.
- Preference. Plenty of people just like how it looks.
Every major operating system now offers it, and most major email clients respect the system setting. You don’t need an adoption statistic to justify designing for it. A meaningful share of your list is reading in dark mode right now.
How Each Email Client Handles Dark Mode
Clients fall into three groups.
No change. The client renders your email as you built it. Your design is safe.
Partial invert. The client flips light backgrounds to dark and dark text to light, but leaves colors that already have enough contrast alone.
Full invert. The client rewrites nearly every color, including ones you set deliberately.
Here’s where the major clients land:
| Client | Behavior |
|---|---|
| Apple Mail (macOS and iOS) | No change |
| Gmail (webmail) | No change |
| Yahoo Mail | No change |
| AOL | No change |
| Outlook.com | Partial invert |
| Outlook (macOS and iOS) | Partial invert |
| Gmail app (Android) | Varies, test it |
| Gmail app (iOS) | Full invert |
| Outlook 2021 (Windows) | Full invert |
| Office 365 (Windows desktop) | Full invert |
| Windows Mail | Full invert |
Apple Mail is worth watching here, since recent iOS updates have changed how it handles mail more broadly.
A word on how solid that table is. Outlook.com and Outlook on Windows are agreed on by every reference we checked. Apple Mail, Gmail webmail, Yahoo, and AOL are agreed on by two of three.
The Gmail Android app is genuinely disputed. Litmus’ chart calls it a partial invert. Email on Acid’s calls it a full invert. Email on Acid also lists Apple Mail as a full invert, where the other two references say no change.
We’re flagging that rather than picking a winner, because the disagreement itself is the useful part. These behaviors change between app versions. No chart is a substitute for testing your own email. Treat any client chart, including this one, as a starting point.
Why Emails Break in Dark Mode
When a client rewrites your colors, a few things go wrong predictably:
- Logos in white boxes. A dark logo on a transparent background gets a light box drawn behind it, or disappears into the dark background.
- Text that vanishes. Black body text usually inverts safely. Colored headings and links often don’t.
- Broken brand colors. Your palette may come out as colors you never chose.
- Unreadable image text. Text baked into an image won’t invert, because the client can’t see it as text.
- Poor contrast. Partial inverts can land you with mid-grey text on a dark grey background.
How to Code for Dark Mode
This is where the original version of this post stopped short. Knowing the best practices doesn’t help much without the code, so here it is.
There are three layers. Each one covers clients the previous one misses.
Step 1: Declare Which Color Schemes You Support
Put these two tags in your <head>:
<meta name="color-scheme" content="light dark">
<meta name="supported-color-schemes" content="light dark">
This tells the client your email is built to handle both schemes, so it doesn’t need to force an inversion on you.
The color-scheme property is a web standard. Per MDN, it “allows an element to indicate which color schemes it can comfortably be rendered in.”
The supported-color-schemes tag is the older Apple-specific form. Include both, since they cost nothing.
Step 2: Add Dark Mode Styles With prefers-color-scheme
Now define what your email should look like in dark mode:
@media (prefers-color-scheme: dark) {
.body-bg { background-color: #1e1e1e !important; }
.card { background-color: #2a2a2a !important; }
h1, h2, p, td, span, a { color: #f5f5f5 !important; }
.btn { background-color: #4f8cff !important; }
.logo-light { display: none !important; }
.logo-dark { display: block !important; }
}
Two things to note. The !important flags aren’t optional here, because you’re overriding styles the client is trying to apply. And swapping a light logo for a dark one is just two classes and a display toggle.
Not every client supports this media query. That’s what step 3 is for.
Step 3: Repeat Your Styles for Outlook.com
Outlook.com ignores prefers-color-scheme. Instead it tags elements whose colors it changed, and you can target those tags.
When Outlook converts a color, it adds data-ogsc to the element. When it converts a background-color, it adds data-ogsb.
So duplicate your dark styles with those prefixes:
[data-ogsc] .body-bg { background-color: #1e1e1e !important; }
[data-ogsb] .card { background-color: #2a2a2a !important; }
[data-ogsc] h1, [data-ogsc] h2, [data-ogsc] p,
[data-ogsc] td, [data-ogsc] span, [data-ogsc] a {
color: #f5f5f5 !important;
}
One catch worth knowing: colors you set inside these rules can themselves get converted. Test the result rather than assuming it holds.
A Dark-Mode-Safe Email Template
Here’s a minimal skeleton with all three layers wired up. Drop your content into the .card table and adjust the colors.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="color-scheme" content="light dark">
<meta name="supported-color-schemes" content="light dark">
<style>
.logo-dark { display: none; }
@media (prefers-color-scheme: dark) {
.body-bg { background-color: #1e1e1e !important; }
.card { background-color: #2a2a2a !important; }
h1, p, td, span, a { color: #f5f5f5 !important; }
.logo-light { display: none !important; }
.logo-dark { display: block !important; }
}
[data-ogsc] .body-bg { background-color: #1e1e1e !important; }
[data-ogsb] .card { background-color: #2a2a2a !important; }
[data-ogsc] h1, [data-ogsc] p,
[data-ogsc] td, [data-ogsc] a { color: #f5f5f5 !important; }
</style>
</head>
<body class="body-bg" style="margin:0; padding:0; background-color:#fffffe;">
<table role="presentation" width="100%" cellpadding="0" cellspacing="0">
<tr>
<td align="center" style="padding:24px;">
<table role="presentation" class="card" width="600"
cellpadding="0" cellspacing="0"
style="background-color:#fffffe; border-radius:8px;">
<tr>
<td style="padding:32px;">
<img class="logo-light" src="logo-dark-text.png" alt="Your brand" width="140">
<img class="logo-dark" src="logo-light-text.png" alt="Your brand" width="140">
<h1 style="color:#111111;">Your headline</h1>
<p style="color:#333333;">Your body copy goes here.</p>
<a class="btn" href="https://example.com"
style="background-color:#4f8cff; color:#ffffff;
padding:12px 20px; border-radius:6px;
display:inline-block; text-decoration:none;">
Take action
</a>
</td>
</tr>
</table>
</td>
</tr>
</table>
</body>
</html>
Notice the background is #fffffe, not pure #ffffff. That’s deliberate, and the next section explains why.
Two things to keep an eye on as you build this out. Inline CSS adds weight fast, and an oversized email can get truncated, so it’s worth knowing about inbox clipping. And if you generate templates in code rather than by hand, our guide to designing email templates in React covers that workflow.
Design Best Practices for Dark Mode
These build on the general principles in our guide to transactional email design, applied specifically to dark mode.
1. Use Off-White and Off-Black, Not Pure Values
The original advice here was to avoid hard-coded background colors and let the client decide. We’d now put it differently, because “let the client decide” means giving up control on full-invert clients.
Some clients trigger inversion on detecting pure #ffffff or #000000. Nudging one digit off often slips past that check:
- Use
#fffffeinstead of#ffffff - Use
#010101instead of#000000
It’s a heuristic, not a guarantee, and it can stop working when a client updates. But it’s widely used and costs nothing to try.
2. Choose Text Colors Carefully
Plain black body text usually inverts cleanly. Colored headings, links, and button labels often don’t.
Check contrast in both modes. A mid-grey that reads well on white can be nearly invisible on dark grey.
Contrast isn’t only an aesthetic question. It’s an accessibility one, and our guide to email accessibility goes deeper on it.
3. Add Dark Mode Styles
Covered in full above. This is the difference between designing for dark mode and hoping it works out.
4. Don’t Overlook Images
Pick images that hold up on both light and dark backgrounds. For logos and icons, ship two versions and swap them.
Background images are worth being careful with, since inversion handles them unpredictably. Test before relying on one, rather than ruling them out entirely.
5. Test in Both Modes, Every Time
Covered below. Testing is the only step here you can’t skip.
Logos, Images, and Email Signatures
Logos cause more dark mode complaints than anything else, and the fix is simple.
Ship two logos. One with dark text for light mode, one with light text for dark mode. Swap them with the display toggle from step 2.
Avoid transparent PNGs for logos with dark text. A transparent background lets the dark surface show through, and dark text on a dark surface is invisible. Either use the two-logo swap or give the logo a small padded background in a color that works both ways.
Add a stroke or glow. For a single logo that has to work everywhere, a thin light outline or subtle glow keeps it legible on either surface.
Email signatures need the same treatment. Signatures are usually where the transparent-logo problem shows up first, because they’re pasted into clients you don’t control. Keep signature images simple, avoid text baked into images, and don’t rely on a white background being there.
Troubleshooting: Why Is My Email Still White?
A few specific failures and what causes them.
“My email is still white in Gmail dark mode.” Gmail webmail doesn’t change email colors at all, so a white email stays white. That’s expected. The Gmail mobile apps behave differently from the web client, so check which one you’re looking at before treating it as a bug.
“My dark mode styles are being ignored.” The client probably doesn’t support prefers-color-scheme. Outlook.com is the common case. Add the data-ogsc and data-ogsb rules from step 3.
“My logo has a white box around it.” One of two causes. Either the logo is transparent and the client drew a light surface behind it, or the file has a white background you can’t see in light mode. Ship a dark mode version.
“Only some of my text changed color.” You’re on a partial-invert client. It converted the colors it thought needed converting and left the rest. Set your text colors explicitly in your dark mode block.
“It looks right in one Outlook and wrong in another.” That’s normal. Outlook.com partially inverts, while Outlook 2021 on Windows fully inverts. They’re different rendering engines with the same name. If Outlook is giving you trouble beyond rendering, we have a separate guide on deliverability to Outlook addresses.
“My button vanished.” The button background was inverted to something close to the surrounding background. Set .btn colors explicitly in both dark mode blocks.
How to Test Your Emails in Dark Mode
There’s no substitute for looking at the real thing.
Test on real devices first. Turn on dark mode on your own phone and desktop, then send yourself the email. This catches the obvious breakage in about a minute and costs nothing.
Check the three behavior groups. You don’t need every client. Pick one from each group instead:
- No change: Apple Mail or Gmail webmail
- Partial invert: Outlook.com
- Full invert: Outlook on Windows, or the Gmail iOS app
Use a rendering preview tool for breadth. Dedicated email testing services render your email across dozens of client-and-device combinations, including light and dark variants. That’s the practical way to cover clients you don’t own.
Re-test after client updates. Dark mode handling changes with app versions. An email that rendered correctly last year may not today, which is the main reason client charts drift out of date.
Test every template once, then re-test whenever you change colors, logos, or layout. Our guide to email testing best practices covers how to fit this into a repeatable process.
Make Sure Your Emails Actually Arrive
A perfectly rendered dark mode email is worth nothing if it lands in spam.
SendLayer handles the delivery side, so the design work isn’t wasted. You get guided domain authentication, so SPF, DKIM, and DMARC are configured properly from the start. Detailed logs show you what was delivered, what bounced, and why.
Frequently Asked Questions About Dark Mode Emails
Do I need to build a separate email for dark mode?
No. You build one email that adapts. The meta tags, a prefers-color-scheme block, and the data-ogsc duplicates cover it.
Why does my email look different in Outlook.com and Outlook for Windows?
They render differently despite the shared name. Outlook.com partially inverts colors and ignores prefers-color-scheme. Outlook 2021 on Windows fully inverts.
Does Gmail support dark mode for emails?
Gmail webmail leaves your email’s colors alone. The Gmail mobile apps do alter them, and the iOS app fully inverts. Test the apps separately from the web client.
Will off-white backgrounds always stop color inversion?
No. It’s a widely used trick, not a rule, and clients can change their detection at any time. Treat it as one layer of defense and test the result.
How do I stop my logo getting a white box in dark mode?
Ship a dark mode version of the logo and swap it with a display toggle inside your dark mode styles. Avoid relying on a transparent background.
Do dark mode styles affect deliverability?
No. Colors and media queries don’t influence whether you reach the inbox. Authentication, domain reputation, and list quality do.
That’s it! Now you know how to design emails for dark mode.
Next, would you like to learn about the benefits and disadvantages of no-reply email addresses? Check out our article on no-reply email pros and cons for more information.
