Dark mode in HTML email

The new big trend in tech, dark mode, is coming to email. Learn how it works and how to make dark‑mode‑friendly HTML emails yourself.

With the new iOS 13 update, Apple Mail is getting a dark theme and becomes the first major email client that supports `prefers-color-scheme` CSS media query – this means you can now design emails specifically for both dark and light themes.

I'm a massive dark mode fan, and blindingly-bright email is my nemesis so when I learned about the dark mode in iOS 13, I did the only obvious thing and ordered a brand new iPhone to test things out.

While I was at it, I also tested how dark mode works in almost all email clients, including the trouble maker Outlook, and here's what I found.

What is prefers-color-scheme?
The prefers-color-scheme CSS media query is used to detect whether the user prefers a light or dark theme, making it possible to design email specifically for both. With the iOS 13 update, the support in most popular email clients jumped from 2.3% to 38.4%! A huge step thanks to Apple Mail's popularity. Surprisingly, Outlook was the only email client that supported this before Apple Mail.

How dark mode works in popular email clients

To render the email message dark itself, email clients invert email's colors automatically behind the scenes. For regular user-to-user emails, this works well and consistently in all email clients.

However, it's not that simple for custom HTML emails – those that fill most of our inboxes. I'm talking transactional and promotional.

Here're the differences I found in how email clients handle dark mode email rendering:

Email client Popularity Dark UI Auto-invert email colorsSupports @media (prefers-color-scheme)
Apple Mail
iPhone + iPad
36.1% Yes Yes
(if transparent background)
YesShow screenshot
Gmail
Android 10
27.8% * Yes Yes
(if transparent background)
NoShow screenshot
Note: This is a reported behaviour, I cannot confirm this ATM. Read more below.
Gmail
iOS 13
27.8% * No No NoShow screenshot
Note: Dark more is coming, already teased with dark splash screen.
Gmail
webmail
27.8% * Yes No NoShow screenshot
Note: Support for dark UI theme, but not the actual emails.
Outlook
iOS 13
9.1% * Yes Yes
(forced if not already dark)
NoShow screenshot
Outlook
Android 10
9.1% * Yes Yes
(forced if not already dark)
NoShow screenshot
Outlook
Windows 10
9.1% * Yes Yes
(forced if not already dark)
NoShow screenshot
Outlook
macOS
9.1% * Yes Yes
(forced if not already dark)
YesShow screenshot
Note: Buggy border color - if border color is changed with prefers-color-scheme it still tries to invert border color even if it's already dark.
Apple Mail
macOS
7.5% Yes Yes
(if transparent background)
NoShow screenshot
Yahoo!
webmail
6.3% * Yes No NoShow screenshot
Note: Support for dark UI theme, but not the actual emails.
AOL
webmail
6.3% * No No NoShow screenshot
Outlook.com
webmail
2.3% Yes Yes
(forced if not already dark)
YesShow screenshot
Windows 10 Mail
Windows 10
0.5% Yes Yes
(forced if not already dark)
NoShow screenshot
Note: The worst email client from the bunch, doesn't even support border-radius.
Zoho Mail
webmail
less than 0.5% Yes Yes
(forced if not already dark)
NoShow screenshot
Note: Inverts color hue, eg.: blue becomes orange.
Mozilla Thunderbird
Windows 10
less than 0.5% Yes No YesShow screenshot
Note: The only email client tested which doesn't forcefully auto-invert email colors, but supports prefers-color-scheme.

* Popularity is shared across all platforms for the same email client because it cannot be reliably distinguished.

Popularity source: Litmus, the 2019 email client market share

How to make HTML emails dark mode friendly

I already put the data to the use, and a few Outlook related challenges later, I made our emails dark mode friendly. Here's how you can do the same:

What the data say
More than 55% of emails might be opened with dark mode enabled. Once Gmail joins the dark side, emails that might be opened with dark mode enabled will skyrocket to 83%!

1) Adjusting colors

Look out for Apple Mail as inverts colors only if the background color is transparent or unspecified – white background won't do. The easiest way to make sure your emails won't blind anybody is to check whether a background color is specified. For more control over the design, this is where prefers-color-scheme comes in handy.

Syntax (@media prefers-color-scheme):

<style>
	/* Your light mode (default) styles: */
	body {
		background: white;
		color: #393939;
	}

	@media (prefers-color-scheme: dark) {
		/* Your dark mode styles: */

		body {
			background: black;
			color: #ccc;
		}
	}
</style>

A design tip: Avoid pure white (#fff) as the text color. I found that contrast ratio around 11.5 for the main text is a nice compromise between not too bright a not too dim. Check the contrast ratio here: https://contrast-ratio.com or use Chrome dev tools.

Switching between light and dark logo version in HTML email with prefers-color-scheme media query

2) Switching between light and dark logo

A dark text on a dark background is pretty much invisible, and that's precisely what happens to a logo if viewed in an email client with enabled dark mode.

Nowadays, a typical logo usually has a transparent background, colorful icon, and dark copy. See the problem? Because email clients don't invert image colors, you need to handle it yourself.

To tackle this, you can either:

  1. the easiest way to fix this is to save the logo with a white background instead of a transparent background, but I wouldn't recommend this approach – dark mode users won't be happy
  2. put a light logo on dark background, rest of the email is on white background (see how Litmus does it)
  3. make dark mode email your default, a good candidate for this would be Spotify as they only offer dark theme in their apps
  4. include both light and dark versions of your logo and switch between with prefers-color-scheme media query

My favorite is the last approach, here's how you do it:

Simple `display: none` on the dark logo works just fine in all modern email clients, but to everyone's surprise, not in Outlook and Windows 10 Mail.

In CSS styles:

<style>
	@media (prefers-color-scheme: dark) {
		.darkLogo {
			display: none !important;
		}

		.lightLogoWrapper,
		.lightLogo {
			display: block !important;
		}
	}
</style>

…and the HTML structure:

<image src="dark-logo.png" class="darkLogo" />

<!--
	To hide the light logo perfectly in Outlook and Windows 10 Mail, 
	you need to wrap the light logo image tag with a div.
-->
<div class="lightLogoWrapper" style="mso-hide: all; display: none">
	<image src="light-logo.png" class="lightLogo" style="display: none" />
</div>

This approach works pretty well, but it still won't work correctly across the board. The dark text on dark background issue will happen with email clients that do support dark mode but doesn't support prefers-color-scheme. That is Outlook, Windows 10 Mail, Zoho, and potentially Gmail.

Bulletproof method: switching between light and dark logo version in HTML email with prefers-color-scheme media query

So, to make the logo in email fully bulletproof, I'll combine the method 1) and 4) from above. Method 1) will cover all email clients that support dark mode, but not the prefers-color-scheme. And method 4) will cover Apple Mail, Outlook on macOS, Outlook.com, which do support both.

Also, instead of saving the logo on a white background, I'll add 3-pixel wide background-matching border and save it on a transparent background as usual.

It's starting look pretty complex (just for a logo), so let's see the HTML markup first:

<!-- Default logo with 3-pixel wide background-matching border -->
<image src="dark-logo-with-background.png" class="darkLogoDefault" />

<!-- Light theme (so dark logo): 
This is for Apple Mail, Outlook on macOS, Outlook.com -->
<div class="darkLogoWrapper" style="mso-hide: all; display: none">
	<image src="dark-logo.png" class="darkLogo" style="display: none" />
</div>

<!-- Dark theme (so light logo): 
This is for Apple Mail, Outlook on macOS, Outlook.com -->
<div class="lightLogoWrapper" style="mso-hide: all; display: none">
	<image src="light-logo.png" class="lightLogo" style="display: none" />
</div>

…and CSS styles:

<style>
	@media (prefers-color-scheme: light) {
		.darkLogoDefault,
		.lightLogo {
			display: none !important;
		}

		.darkLogoWrapper,
		.darkLogo {
			display: block !important;
		}
	}

	@media (prefers-color-scheme: dark) {
		.darkLogoDefault,
		.darkLogo {
			display: none !important;
		}

		.lightLogoWrapper,
		.lightLogo {
			display: block !important;
		}
	}
</style>

Dark mode in Gmail is coming

The dark mode is coming to Android in the new Android 10, and Gmail should go completely dark too, finally. All you need is Android 10 and newest Gmail (at least version 2019.09.01.268168002). However, Google tends to enable new features (a dark theme in this case) for users gradually with a server-side push, and I haven't got the luck for now.

I'm curious to see if support for @media prefers-color-scheme is coming to Gmail. From what I read, it doesn't seem promising. I guess we have to wait to find out. I'll update the article once I get the dark theme in Gmail enabled.

Wrapping up

Dark mode is coming to HTML email, and I love it! But, it's another thing to worry about, like using HTML tables for layout wasn't enough.

Stay up-to-date about the dark mode in email by joining our mailing list. We also share there insights and challenges we face while building and growing our SaaS product – Sidemail.

Thanks for reading!

About Sidemail

Grow your SaaS with the right email tools

Sidemail is everything you need to communicate well with your customers: email sending API, targeted messaging, and so much more. Learn more →