Preview first. Panic less.
← Back to MailMode
MailMode Learn Technical reference

Email Client Dark Mode Support Matrix

A technical comparison of how major email clients handle dark mode, colour inversion, authored CSS and MailMode preview modes.

Published:  Last updated: 
familiesApple / Gmail / Outlook
modesNo-change / partial / full
ruleMatrix first, client test next
No-change

Apple Mail default / Gmail Web

Client UI can be dark while rich HTML email is largely left as authored.

Authored dark CSS

Apple Mail first

Samsung Email and Thunderbird can support authored dark CSS in some contexts, but version, platform and account setup matter.

Partial invert

Outlook.com / Gmail Android

Selective transformations can rewrite some colours, backgrounds, text and borders.

Full invert

Gmail iOS / classic Outlook

Aggressive forced dark behaviour can break already-dark designs, logos and CTAs.

This is an independent MailMode reference, not official documentation from any email client provider. Dark mode behaviour can change by client version, app, OS, account type and rendering engine.

How to read this matrix

Client labels are behaviour families, not exact emulators

No-change

Dark app shell, light message

Rich HTML is largely left unchanged even when the surrounding client UI is dark.

Authored dark CSS

Sender-controlled dark state

The client can respect dark CSS such as prefers-color-scheme when support is declared and tested.

Partial invert

Selective colour rewriting

The client changes some text, backgrounds, borders or attributes while preserving other areas.

Full invert

Aggressive forced dark

The client aggressively transforms the email and can break already-dark designs.

Test required

Behaviour varies

Platform, version, account type and rendering engine can change the final result.

Key takeaways

The practical dark mode map

Apple Mail

Strongest authored CSS target

Apple Mail is generally the clearest place to use color-scheme, supported-color-schemes and prefers-color-scheme.

Gmail Web

Usually no-change for rich HTML

Gmail Web often darkens the app shell while leaving rich HTML largely unchanged; CSS support does not mean dark-mode control.

Gmail iOS

High-risk full invert

Already-dark panels, white logos and pale text can be aggressively transformed.

Gmail Android

Chromium-style darkening

It is usually closer to algorithmic partial inversion than Gmail iOS full invert, and needs Android-specific Gmail checks.

Classic Outlook Windows

Full invert plus MSO/VML risk

Classic Outlook is still the Word-engine client; keep it separate from new Outlook, web Outlook and mobile Outlook.

Outlook.com

Partial invert with data attributes

data-ogsc and data-ogsb are useful Outlook.com-style targeting hooks; prefers-color-scheme is not the main control surface.

New Outlook

Separate test target

Public evidence points toward web/PWA-style behaviour, but not exact parity with Outlook.com or classic Outlook.

Client behaviour matrix

Major email client dark mode behaviour

Matrix notes are based on public email-client documentation, Can I Email feature tables, WebKit, Gmail and Microsoft references, and email developer testing sources. Behaviour can vary by app version, account type and platform.

ClientDefault behaviourRich HTML unchanged?Best dark CSS pathControlMailMode modeKey caveatRelated guide
Apple Mail macOSNo-change by default / authored dark or partial when opted inMostly yesprefers-color-scheme + color-schemeHigh controlAuthored CSS / no changeMail uses scheme declarations as a signal; test macOS separately.Apple Mail
Apple Mail iOSNo-change by default / authored dark CSS when opted inMostly yesprefers-color-scheme + color-schemeHigh controlAuthored CSSTest device layouts.Apple Mail
Apple Mail iPadOSAuthored CSS / iOS-likeMostly yesprefers-color-scheme + color-schemeHigh controlAuthored CSSTreat as iOS-like, but test tablet layouts and device bugs.Apple Mail
Gmail WebNo-changeYesOrdinary light HTML; no reliable dark queryMedium controlNo changeGmail supports many CSS features, but not a reliable prefers-color-scheme dark toggle.Gmail
Gmail iOSFull invertNoGmail-specific hacks onlyLow controlFull InvertHigh-risk for already-dark designs.Gmail
Gmail AndroidPartial invert / algorithmic darkeningPartialdiv > u + .body / defensive CSSMixed controlPartial InvertChromium-style darkening; materially different from Gmail iOS.Gmail
GANGAReduced CSS / partial invert riskPartial / noVery limited; avoid relying on Gmail hacksLow controlPartial InvertGmail style support is reduced for non-Google accounts.Gmail
Outlook classic WindowsFull invertPartial / noMSO, VML, defensive coloursMixed controlFull InvertWord engine, not new Outlook.VML
New Outlook for WindowsTest required / likely web-style partialPartialOutlook.com-like defensive CSS; no classic VML assumptionsMixed controlPartial Invert / test requiredWebView2-based, but not proven identical to Outlook.com.Outlook
Outlook.com / Outlook webPartial invertPartial[data-ogsc] / [data-ogsb]Medium controlPartial InvertCan prefix classes and rewrite colours inline with !important.Outlook
Outlook for MacPartial invertPartialLimited / test requiredMixed controlPartial InvertOften preserves many backgrounds but can flip black/white values.Outlook
Outlook iOSPartial invert / atypicalPartialNo reliable public selectorLow controlPartial InvertUsually less invasive than Gmail iOS, but test on device.Outlook
Outlook AndroidPartial invertPartialTest on deviceLow controlPartial InvertNot a VML client.Outlook
Yahoo MailVariesVariesNo standard path; platform testing requiredLow controlTest required / partial fallbackWeb/iOS can differ from Android forced-dark behaviour.CSS
Samsung EmailVaries / authored CSS in some contextsPartial / yesprefers-color-scheme where supported; scheme hints may helpMixed controlAuthored CSS / partial fallbackAccount type, app version and provider can matter, especially Microsoft accounts.CSS
ThunderbirdVersion-dependentVariesprefers-color-scheme where supportedMixed controlAuthored CSS / test requiredDesktop settings, app version and Android forced-dark behaviour can diverge.CSS
MailMode preview mapping

Which MailMode mode to check first

No-change

Baseline clients

Gmail Web and Apple Mail rich HTML baseline without authored dark CSS.

Authored dark CSS

Sender-designed dark state

Apple Mail first, plus Samsung Email and Thunderbird only when the target environment honours authored dark CSS.

Partial Invert

Selective client transforms

Gmail Android, GANGA, Outlook.com, Outlook mobile, Outlook Mac, likely new Outlook paths and unknown Yahoo/Samsung fallbacks.

Full Invert

Worst-case forced dark

Gmail iOS and classic Outlook Windows.

Test required

Variable families

Yahoo Mail, Thunderbird, Samsung Email and new Outlook should be checked against target versions.

Technique support matrix

Dark mode techniques by client family

Technique support describes practical email-development reliability, not just raw CSS support. Some clients support a CSS feature but still transform colours in dark mode.

TechniqueBest useStrong clientsWeak clientsCaveatRelated guide
@media (prefers-color-scheme: dark)Good target authored dark CSSApple Mail first; selected Samsung Email and Thunderbird contextsGmail, Yahoo, classic OutlookSelected clients only; Gmail does not provide a reliable dark-mode media-query path.CSS
color-scheme meta / root CSSDeclare light and dark supportApple / WebKit-style clients; selected Samsung Email pathsGmail, most Outlook surfaces, YahooApple-first signal, not a global switch.Apple Mail
supported-color-schemes metaLegacy Apple compatibilityOlder Apple / WebKit / Mail pathsMost non-Apple clientsUseful alongside color-scheme, but not a Gmail or Outlook control.Apple Mail
CSS custom propertiesUse with cautionSome modern clientsGmail, Outlook, Yahoo riskDo not use as only production colour system.CSS
Embedded <style> blocksClient-specific patchesApple, Gmail accounts, Outlook.comGANGA, body styles in Gmail, sanitised contextsSupport is not dark mode control; Gmail has style placement and size caveats.CSS
Inline stylesDefensive fallbackBroad baselineForced dark can rewrite coloursStill transformed by some clients.CSS
!importantProtect authored rulesAuthored CSS pathsForced transforms, Outlook.com rewritesOutlook.com can mutate colours inline with !important.CSS
display:none / max-heightImage swapsApple, Gmail, Yahoo, Samsung and many modern clientsClassic Outlook caveatsdisplay:none has classic Outlook inheritance bugs; pair with max-height.Apple Mail
Background colours / bgcolorTable-cell resilienceBroad light-mode fallbackOutlook.com, Outlook family, Gmail mobile forced-dark casesBaseline resilience, not a dark-mode lock.CSS
Background images / one-colour gradientsSpecialist surface preservationApple Mail; selected Gmail contextsOutlook Windows, GANGA, Yahoo; some Gmail Android inline casesUseful in Gmail iOS fixes, but not universal.Gmail
Light/dark image swappingLogo and icon contrastApple-style authored dark CSS clientsGmail forced dark, Outlook variationsUse hosted assets and test; do not assume every client will reveal the dark asset.Apple Mail
CSS filtersUse with cautionLimited targeted casesMost email clientsBroad support is poor and filters can damage brand assets.CSS
mix-blend-modeTargeted Gmail iOS contrast fixesGmail account paths where supportedGANGA, Outlook, YahooNot broad support.Gmail
u + .body / div > u + .bodyGmail targetingGmail accountsGANGA and non-Gmail clientsGmail-only pattern.Gmail
[data-ogsc] / [data-ogsb]Outlook.com dark patchesOutlook.com / OWAApple, Gmail, classic Outlook; not proven across every Outlook appDo not assume identical reliability across Outlook mobile apps.Outlook
MSO conditionals / VMLClassic Outlook Windows fallbacksClassic Outlook WindowsNew Outlook, web, mobile, Apple, GmailWord-engine-only; VML and HTML colours can still mismatch in dark mode.VML
Client families

Group behaviour before choosing fixes

Apple Mail family

High developer control

Best authored dark CSS target, especially when scheme declarations are intentional. Start with the Apple Mail guide and Dark Mode CSS guide.

Gmail family

Split Web, iOS, Android and GANGA

Web is no-change, iOS is full invert, Android is Chromium-style partial darkening, and GANGA has reduced CSS. See the Gmail guide.

Outlook family

Do not treat Outlook as one client

Classic Windows, Outlook.com, new Outlook, Mac and mobile need different assumptions. Keep data-og patches separate from MSO/VML fallbacks.

Other clients

Yahoo, Samsung and Thunderbird vary

Yahoo differs by platform, Samsung Email can depend on account type and app version, and Thunderbird desktop should not be treated as identical to Thunderbird Android.

Common risks

Assumptions that break dark mode emails

Universal CSS

Treating prefers-color-scheme as universal

Affected: Gmail, Yahoo, Outlook Windows. Safer: pair standards CSS with client-specific fallbacks.

Gmail split

Assuming Gmail Web and mobile match

Affected: Gmail family. Safer: test Web, iOS, Android and GANGA separately.

Gmail mobile

Assuming iOS and Android match

Affected: Gmail apps. Safer: treat iOS as full-invert risk and Android as partial-invert risk.

Outlook split

Assuming Outlook.com and classic Outlook match

Affected: Outlook family. Safer: separate data-og patches from MSO/VML fallbacks.

New Outlook

Assuming new Outlook equals classic Outlook

Affected: Windows Outlook. Safer: treat new Outlook as a separate test target.

CSS support

Assuming CSS support equals dark mode control

Affected: Gmail and Yahoo. Safer: separate feature support from forced-dark behaviour.

Logo contrast

Using one logo for every background

Affected: forced and partial dark clients. Safer: use backing surfaces, outlines or dark-specific assets.

Variables

Relying entirely on CSS variables

Affected: mixed-support clients. Safer: include literal fallback colours.

VML scope

Using VML outside classic Outlook assumptions

Affected: new Outlook, web, mobile. Safer: keep VML for classic Outlook Windows only.

Other clients

Treating Yahoo, Samsung or Thunderbird as fixed

Affected: mixed-client audiences. Safer: split platforms and account types where they matter.

Colour locks

Treating bgcolor as a dark-mode lock

Affected: Outlook.com, Outlook family, Gmail mobile. Safer: use it for baseline fallback, then test forced-dark rewrites.

Outlook.com

Assuming !important wins

Affected: Outlook.com and OWA. Safer: expect inline colour mutation and verify data-og targeting.

Caveats

Where the matrix needs careful interpretation

  • New Outlook for Windows is a separate test target, not classic Outlook with a new skin.
  • Yahoo Mail should ideally be split by web, iOS and Android when that audience is important.
  • Thunderbird should ideally be split by desktop, Android and version where that audience matters.
  • Samsung Email can support authored dark CSS in some contexts, but behaviour can vary by account type, app version and provider.
  • Feature-support data and forced-dark behaviour are different kinds of evidence.
  • Gmail can support useful CSS properties while still lacking a reliable dark-mode media-query control.
  • Outlook.com can offer rich HTML/CSS support while still rewriting colours inline.
  • Client behaviour changes over time, so this matrix should be periodically reviewed.
MailMode mapping

How this supports MailMode previews

MailMode is not an exact emulator for every email client. Its preview modes are practical approximations that help expose common dark mode risk families before real-client testing.

No-change checks help with Gmail Web and rich HTML Apple Mail baselines. Authored CSS helps with Apple Mail-style dark CSS, and with Samsung Email or Thunderbird only when the target environment is known to honour authored dark styles.

Partial Invert helps approximate Gmail Android, GANGA, Outlook.com/OWA, Outlook Mac, Outlook mobile, likely new Outlook paths, and unknown Yahoo/Samsung fallbacks. Full Invert helps expose Gmail iOS and classic Outlook Windows-style worst cases.

Related guides: Dark Mode CSS · Outlook · Gmail · Apple Mail · Outlook VML · MJML · React Email

1. Identify client family 2. Choose preview mode 3. Check risky colours 4. Test real clients
Related Guides

Keep exploring MailMode Learn

Read nextOutlook Dark Mode Behaviour

Classic Outlook, Outlook.com and Microsoft 365 dark mode behaviours.

 Read nextGmail Dark Mode Email Rendering

Gmail Web, iOS, Android and GANGA rendering risks.

 Read nextApple Mail Dark Mode Rendering

Standards-friendly dark CSS, image swaps and Apple Mail quirks.

 Read nextDark Mode CSS for HTML Email

Meta tags, media queries, client targeting and defensive patterns.

 Read nextOutlook VML Buttons and Dark Mode

Classic Outlook button fallbacks, VML fills and dark mode risks.
References

Sources & Further Reading

Last Updated: Sources Reviewed: