Skip to main content
Most email clients now offer a dark mode that automatically adjusts email colors. Gmail, Apple Mail, Outlook, and Yahoo Mail each handle dark mode differently — some invert colors, some blend backgrounds, and some leave emails untouched. Without defensive design, your carefully crafted email can end up with invisible text, clashing colors, or unreadable content in dark mode.

​
How Email Clients Handle Dark Mode

Email clients use three different strategies to render emails in dark mode, and the strategy varies by client and platform.
You cannot rely on any single strategy. Your email needs to look acceptable under all three scenarios. The techniques in this guide are defensive — they ensure readability regardless of what the client does.

​
Defensive Design Fundamentals

​
Always Set Explicit Colors

The most important rule for dark mode compatibility: never rely on default colors. If you don’t set a text color, the email client decides — and in dark mode, that default might become white text on a white background you specified.

​
Set Both bgcolor and background-color

Outlook desktop uses the bgcolor HTML attribute, while other clients use CSS background-color. Set both.

​
Avoid Pure Black and Pure White

Pure white (#ffffff) backgrounds and pure black (#000000) text create harsh contrast in both modes. Use near-white and near-black values that feel softer and adapt better when inverted.

​
Images in Dark Mode

​
Add Backgrounds to Transparent Images

Logos and icons with transparent backgrounds are the most common dark mode casualty. A dark logo on a transparent PNG becomes invisible when the background turns dark.
Export logos as PNG with a built-in white or light padding around the artwork. This creates a visible “safe zone” around the logo regardless of the email background color.

​
Use Images With Built-In Contrast

For hero images and banners, ensure the image itself contains enough contrast to be readable on both light and dark backgrounds. Avoid images that bleed into the email background.

​
Dark Mode Meta Tag

Some email clients (notably Apple Mail and some versions of Gmail) support a meta tag that indicates your email is dark-mode-aware. Adding this can prevent the client from applying its own color transformations.
This meta tag tells the email client “I handle dark mode myself.” If you add it, you must provide dark mode styles via @media (prefers-color-scheme: dark). Adding the meta tag without corresponding styles can result in a broken appearance.

​
CSS Dark Mode Styles

For clients that support <style> blocks and the prefers-color-scheme media query, you can provide explicit dark mode overrides. Note that many email clients strip <style> blocks, so these are progressive enhancements — your email must still look acceptable without them.
The inline styles serve as the default (light mode) appearance. The @media (prefers-color-scheme: dark) block overrides them for clients that support it. The !important declarations are necessary because inline styles have higher specificity.

​
Buttons in Dark Mode

Buttons are particularly vulnerable to dark mode issues. A white button on a light background can become invisible, or a dark button can lose its border against a dark background.

​
Bulletproof Dark Mode Buttons

Key principles:
  • Use a background color with enough contrast against both light and dark email backgrounds
  • Add a border matching the button color — if the background gets inverted, the border maintains the button shape
  • Use white text on colored buttons — white text stays readable against most inverted backgrounds

​
Testing Dark Mode

​
Manual Testing

Test your emails in dark mode on these clients, which cover the main rendering behaviors:
1

Apple Mail (macOS)

System Preferences → Appearance → Dark. Apple Mail generally respects prefers-color-scheme and applies minimal auto-inversion.
2

Gmail (iOS and Android)

Gmail aggressively inverts colors in dark mode, especially on Android. Enable dark mode in the Gmail app settings and send yourself a test email.
3

Outlook Desktop (Windows)

Outlook’s Word-based renderer applies full color inversion. File → Office Account → Office Theme → Dark Gray or Black. This is typically the most aggressive dark mode.
4

Outlook.com (Web)

Click the gear icon → Dark mode. Outlook.com applies partial inversion and sometimes ignores explicit colors.
Use Lettr’s test email feature to send tests to your own accounts. Check both light and dark mode every time you update a template.

​
What to Check

​
Common Mistakes

If you don’t set an explicit text color, the email client assigns one. In dark mode, the client may change it to white — which becomes invisible if you’ve set a white background that the client didn’t invert. Always set explicit colors on every text element.
A dark-colored logo on a transparent background disappears completely when the email background is inverted to dark. Either export logos with a built-in light background, or wrap the image in a container with an explicit white background.
The color-scheme: light dark meta tag tells the client you handle dark mode. If you declare this but don’t provide @media (prefers-color-scheme: dark) styles, the client may not apply any automatic adjustments, leaving your email unreadable in dark mode.
Each email client handles dark mode differently. An email that looks perfect in Apple Mail dark mode may be unreadable in Outlook desktop dark mode. Test across at least three clients.
Background images in CSS (background-image) are unsupported in many email clients and don’t adapt to dark mode at all. Use solid background colors for containers.

Templates

Build and manage email templates with the Topol editor

Email Accessibility

Make your emails accessible to all recipients

Email Rendering Across Clients

How different email clients render HTML email

Test Emails

Send test emails before going live