Dark Mode Guide

How email clients handle dark mode

Different clients apply dark mode differently:

Color inversion — light backgrounds become dark, dark text becomes light
Media queries — prefers-color-scheme: dark styles are applied
Selective override — only certain elements are modified
No change — the email content is left untouched by the client's dark mode

Testing dark mode with Emailens

import { transformForClient, simulateDarkMode } from "@emailens/engine";

const transform = transformForClient(html, "gmail-web");
const darkMode = simulateDarkMode(transform.html, "gmail-web");

// Check for dark-mode-specific warnings
console.log(darkMode.warnings);

Or via the API — the response includes a darkMode object with variants for each client.

Best practices

Use `prefers-color-scheme`

Add dark mode styles in a media query:

<style>
  @media (prefers-color-scheme: dark) {
    .email-body { background-color: #1a1a1a !important; }
    .email-text { color: #e0e0e0 !important; }
  }
</style>

This is respected by Apple Mail, Outlook 365, and some others.

Use transparent images

Logos and icons with transparent backgrounds work better in dark mode than those with white backgrounds.

Avoid hardcoded light backgrounds

Instead of background-color: white, consider using transparent or easily-invertible colors.

Add `color-scheme` meta

Tell email clients your email supports dark mode:

<head>
  <meta name="color-scheme" content="light dark">
  <meta name="supported-color-schemes" content="light dark">
</head>

Test both variants

Always preview both light and dark mode. The Emailens web app shows both side by side, and the API returns both variants per client.

Client-specific behavior

Client	Dark mode approach
Gmail (all)	Aggressive color inversion + respects `prefers-color-scheme`
Outlook 365	Respects `prefers-color-scheme`, moderate inversion
Outlook (New)	Partial inversion (same as Outlook 365)
Outlook Classic	Full color inversion
Apple Mail (all)	Full `prefers-color-scheme` support
Yahoo Mail	Color inversion
Samsung Mail	Aggressive color inversion
Thunderbird	No dark mode

On this page