DEV Community: Mailpeek

Dark Mode is still breaking your HTML emails. Here is the logic to fix it.

Mailpeek — Thu, 05 Mar 2026 12:37:45 +0000

Email clients like Gmail and Outlook don't just "invert" colors; they apply unpredictable, proprietary rendering logic that can ruin your brand's UI.

I'm currently building Mailpeek, a Vue-based suite to solve this. While building the preview engine, I had to deep-dive into how these clients actually handle color inversion. Here is the logic I used to build a reliable dark mode emulator and how you can apply it to your own emails.

Building for email doesn't have to feel like coding for a browser from 2004. We have the tools in the Vue ecosystem to make this better.

Dark Mode in Email: Why Every Client Does It Differently

You test your email in Gmail. It looks great. You toggle dark mode and check again. Still looks great. You relax.

Then a user on Gmail iOS screenshots your email and your white logo has vanished into a black background, your carefully chosen brand colours have been replaced with something you have never seen before, and your call-to-action button now blends into the surrounding content.

This is dark mode in email. There is no spec. There is no standard. Every client does whatever it wants.

The Three Dark Mode Strategies

Email clients fall into three broad categories when it comes to dark mode. Understanding which strategy each client uses is the key to not being surprised by what your users see.

Strategy 1: No transformation

The client darkens its own UI (the toolbar, sidebar, message list) but leaves the email body completely untouched. Your email renders exactly as you wrote it - light background, dark text, everything intact.

This sounds ideal, but it creates a jarring experience. Your bright white email sits inside a dark UI, like a flashlight in a dark room. Users notice, and some will blame your email for "not supporting dark mode" even though the client chose not to transform it.

Clients that use this strategy:

Gmail web (desktop browser)

Strategy 2: Full colour inversion

The client applies a blanket colour inversion across the entire email body. Light backgrounds become dark. Dark text becomes light. Images get inverted and then re-inverted so photographs do not look like negatives.

This is the most aggressive approach. It transforms everything, which means it also breaks things. A dark-on-dark section in your original email becomes light-on-light after inversion. Transparent PNGs with dark content disappear. Brand colours shift to their complementary opposites.

Clients that use this strategy:

Gmail iOS app
Gmail Android app (varies by device)

Strategy 3: Partial inversion

The client selectively replaces specific colours rather than inverting everything. It targets background colours and text colours individually, attempting to create a dark version that preserves the visual hierarchy without flipping the entire palette.

This sounds smarter than full inversion, and sometimes it is. But "selective" means the client is making judgment calls about which colours to replace and what to replace them with. Those judgments do not always match your design intent. A brand green might become a shade of teal. A light grey background might stay light grey while the text on top of it turns white.

Clients that use this strategy:

Outlook desktop (Word engine)
Outlook.com / New Outlook
Apple Mail (macOS and iOS)

What Each Client Actually Does

Gmail Web Desktop: Nothing

Gmail web in dark mode does not touch your email content. The Gmail UI around it goes dark, but the email iframe renders exactly as written. If your email has a white background, it stays white.

This is the easiest client to support in dark mode because there is nothing to support. But it is also why testing only in Gmail web gives you false confidence. You think dark mode is fine when you have not actually tested dark mode at all.

Gmail iOS: Full Inversion

Gmail on iOS applies a CSS filter that inverts the entire email. The algorithm roughly works like this:

Invert all colours (white becomes black, black becomes white, everything in between flips)
Reverse inversion on certain elements so photographs look normal
Re-invert background-image elements for the same reason

The result is that your text and background colours are all inverted, but your images survive. Mostly.

What breaks:

Transparent PNGs with dark content. If your logo is a dark graphic on a transparent background, the inversion turns it light. But because the image is re-inverted to protect photographs, it flips back to dark. Now you have a dark logo on a dark background. It disappears.

/* Your original */
background-color: #ffffff;  /* white */
color: #1a1a1a;            /* near-black */

/* After Gmail iOS inversion */
background-color: #000000;  /* black */
color: #e5e5e5;            /* near-white */

Dark-on-dark sections. If you have a section with a dark background and light text (like a footer or a hero banner), inversion makes it a light background with dark text. That is fine on its own. But if the section next to it was originally light background with dark text (now inverted to dark background with light text), you end up with alternating sections that look inverted from your original design intent.

Brand colours. Every colour gets its complementary opposite. Your brand blue #2563eb becomes #da9c14 (a muddy gold). There is no way to override this from within the email.

Outlook Desktop (Word Engine): Selective Replacement

Outlook's Word rendering engine takes a more surgical approach. Instead of inverting everything, it examines individual elements and replaces colours it deems "too light for dark mode."

The rules are not fully documented, but through testing the behaviour is roughly:

Background colours close to white get replaced with a dark grey (#1e1e1e or similar)
Text colours close to black get replaced with a light grey or white
Colours far from black or white (your brand colours, accent colours) are left alone or shifted slightly
Images are not inverted - they render as-is

This means Outlook dark mode mostly works, but with unpredictable edge cases:

/* Your original */
background-color: #f5f5f5;  /* light grey */
color: #333333;             /* dark grey */

/* Outlook dark mode might render as */
background-color: #2d2d2d;  /* dark grey (replaced) */
color: #d4d4d4;             /* light grey (replaced) */

What breaks:

Mid-range colours. Outlook has to decide where "light" ends and "coloured" begins. A light blue background (#dbeafe) might get replaced with dark grey, or it might be left as-is. The threshold is not consistent across Outlook versions.

Explicit colour pairings. If you set background-color: #1a1a1a and color: #ffffff to create your own dark section, Outlook might not realise you already handled dark mode for that element. It could replace your white text with light grey and your dark background with slightly different dark grey, producing a low-contrast result that is technically readable but visually flat.

Borders and dividers. A border: 1px solid #e5e7eb (light grey border) might disappear against Outlook's dark background, or it might be replaced with something heavier than you intended.

Outlook.com / New Outlook: Lighter Touch

The web and new desktop versions of Outlook use a browser rendering engine (not Word), so they have better CSS support overall. Their dark mode transformation is similar to Outlook desktop's selective approach but less aggressive.

Colours are remapped rather than replaced, producing results closer to a proper dark theme than a colour swap. But the same fundamental problem exists: the client is guessing what your dark mode should look like, and guesses are sometimes wrong.

Apple Mail: Color Scheme Aware

Apple Mail on macOS and iOS is the most standards-friendly. It respects the color-scheme meta tag and the prefers-color-scheme media query, meaning you can actually provide your own dark mode styles that Apple Mail will use.

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

@media (prefers-color-scheme: dark) {
  .email-body {
    background-color: #1a1a1a !important;
    color: #e5e5e5 !important;
  }
  .brand-header {
    background-color: #0f172a !important;
  }
}

If you provide these styles, Apple Mail uses them. If you do not, it falls back to its own partial inversion - similar to Outlook's approach but generally more predictable.

The catch: @media (prefers-color-scheme) is stripped by Gmail, so these styles only work in Apple Mail and a few other clients that support them. You cannot write a single set of dark mode styles that works everywhere.

The Comparison Table

Behaviour	Gmail Web	Gmail iOS	Outlook Desktop	Outlook.com	Apple Mail
Strategy	None	Full inversion	Partial inversion	Partial inversion	Partial inversion
Transforms backgrounds	No	Yes (inverted)	Yes (replaced)	Yes (remapped)	Yes (replaced or CSS)
Transforms text colour	No	Yes (inverted)	Yes (replaced)	Yes (remapped)	Yes (replaced or CSS)
Transforms images	No	Inverts then re-inverts	No	No	No
Respects `prefers-color-scheme`	No	No	No	Partial	Yes
Respects `color-scheme` meta	No	No	No	Partial	Yes
Predictability	High (nothing happens)	Low	Medium	Medium	High (if you provide styles)

Practical Advice

Do not rely on a single dark mode test

If you check dark mode in Gmail web and everything looks fine, you have tested nothing. Gmail web does not transform emails. You need to check at least Gmail iOS (full inversion) and Outlook (partial inversion) to cover the two transformation strategies that actually change your email.

Use solid backgrounds on images

Transparent PNGs are the most common dark mode casualty. If your logo or icon uses transparency, it will likely disappear or look wrong after inversion. Use a solid background colour on the image itself, or provide a version with a built-in background.

Avoid relying on pure white and pure black

Elements with #ffffff backgrounds and #000000 text are the first targets for colour replacement. Using slightly off-white (#fafafa) and slightly off-black (#1a1a1a) does not help - clients are smart enough to catch near-white and near-black values. But being aware that these specific colours will be transformed helps you anticipate the result.

Test your dark-on-dark sections

If your email has sections with intentionally dark backgrounds (hero banners, footers, CTAs), these are the most likely to break. After inversion, they become light sections. After partial replacement, they become slightly different dark sections with potentially lower contrast. Check these areas specifically.

Keep critical information in text, not in styled containers

If a piece of information is only readable because of its background colour or container styling, dark mode can make it unreadable. The text content of your email should make sense even if every background colour changes.

Preview Before You Send

I built @mailpeek/preview specifically because dark mode testing was the most painful part of email development. Sending test emails to multiple devices and toggling dark mode on each one is time-consuming and error-prone.

The preview component lets you toggle dark mode on and off for each client and see the transformation in real time:

<script setup lang="ts">
import { EmailPreview } from '@mailpeek/preview'
import '@mailpeek/preview/style.css'
</script>

<template>
  <!-- Gmail dark mode: no transformation (chrome darkens, email stays the same) -->
  <EmailPreview :html="emailHtml" client="gmail" dark-mode />

  <!-- Outlook dark mode: partial colour inversion -->
  <EmailPreview :html="emailHtml" client="outlook" dark-mode />
</template>

The dark mode approximation covers Gmail's no-op strategy, full colour inversion for iOS clients, and partial inversion for Outlook. It is not pixel-perfect - actual rendering varies between OS versions, app versions, and device settings. But it catches the big problems (disappearing logos, invisible text, broken contrast) before you send.

Both @mailpeek/preview and @mailpeek/components are free, open source, and MIT licensed. Vue 3 only, zero runtime dependencies, full TypeScript support.

npm: @mailpeek/preview and @mailpeek/components
Docs: mailpeek.dev
GitHub: github.com/mailpeek/mailpeek
Live demo: mailpeek.dev/demo

I need your help:

Star the Repo: If you've ever struggled with email CSS, check out Mailpeek on GitHub.

Templates: I’ve just finished a library of 40+ "Dark Mode Ready" patterns and templates (Pricing tables, Newsletters, etc.). They are currently listed as "Coming Soon" on the mailpeek.dev (https://mailpeek.dev), but I’ll be giving early access to GitHub stargazers first.

Let’s swap dark-mode horror stories in the comments!

Why Gmail Breaks Your Email CSS (and How to Catch It Before Your Users Do)

Mailpeek — Wed, 25 Feb 2026 12:12:07 +0000

You spent an afternoon building a beautiful transactional email. The header gradient is perfect. The buttons have rounded corners and a subtle shadow. The layout uses flexbox so everything centres nicely. You send a test to yourself, open it in Gmail, and half the design is gone.

This is not a bug. This is email in 2026.

Email rendering is stuck somewhere around 2004. Gmail runs every incoming email through a custom HTML sanitizer that aggressively strips CSS it considers unsafe or unnecessary. Outlook desktop (2016 through 2021) goes further - it literally uses Microsoft Word as its HTML rendering engine. Word. The word processor. For rendering HTML.

The result is that the CSS you write and the CSS your recipients see are often two completely different things. And unlike web development, there are no DevTools, no error messages, and no way to know what broke until someone screenshots it and sends it to you.

Let's fix that.

What Gmail Actually Strips

Gmail's HTML sanitizer is not documented in full, but between Google's own developer docs, community testing, and resources like caniemail.com, we have a clear picture. Here is what it removes.

@font-face - gone entirely

/* What you wrote */
@font-face {
  font-family: 'BrandSans';
  src: url('https://fonts.example.com/brand-sans.woff2') format('woff2');
}

h1 {
  font-family: 'BrandSans', sans-serif;
}

/* What Gmail renders */
h1 {
  font-family: 'BrandSans', sans-serif; /* Falls back to Arial/Helvetica */
}

The @font-face rule is stripped. The font-family declaration stays, but since the font was never loaded, you get whatever sans-serif fallback the system provides. On most machines, that is Arial.

@media queries - ignored on desktop

/* What you wrote */
@media (max-width: 600px) {
  .container { width: 100% !important; }
  .column { display: block !important; }
}

/* What Gmail desktop renders */
/* Nothing. The entire @media block is removed. */

Gmail desktop strips all @media rules. Your responsive email is not responsive in Gmail desktop. Gmail mobile has partial support, but desktop - which is where a huge percentage of business email is read - ignores media queries completely.

Positioning properties - all stripped

/* What you wrote */
.tooltip {
  position: absolute;
  top: -30px;
  left: 50%;
  z-index: 100;
}

/* What Gmail renders */
.tooltip {
  /* Empty. Every property was stripped. */
}

position, top, right, bottom, left, and z-index are all removed. Any layout that depends on positioned elements will collapse.

CSS Grid - stripped (but flexbox partially survives)

/* What you wrote */
.grid-layout {
  display: grid;
  grid-template-columns: 1fr 1fr 1fr;
  gap: 16px;
}

.flex-layout {
  display: flex;
  align-items: center;
  justify-content: space-between;
}

/* What Gmail renders */
.grid-layout {
  /* display: grid is removed entirely */
}

.flex-layout {
  display: flex; /* Kept! */
  /* But align-items and justify-content are stripped */
}

This is a subtle one. Gmail does support display: flex, but it strips the sub-properties that make flexbox useful -- align-items, justify-content, flex-direction, flex-wrap, and flex. So your flex container exists, but you have no control over how its children are laid out.

Visual effects - stripped

/* What you wrote */
.card {
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
  transform: translateY(-2px);
  transition: transform 0.2s ease;
}

/* What Gmail renders */
.card {
  /* All three properties removed */
}

box-shadow, transform, animation, and transition are all stripped. Your hover effects, entrance animations, and depth cues will not render.

External stylesheets and @import - stripped

<!-- What you wrote -->
<link rel="stylesheet" href="https://example.com/email-styles.css">
<style>
  @import url('https://fonts.googleapis.com/css2?family=Inter');
</style>

<!-- What Gmail renders -->
<!-- The <link> tag is removed entirely -->
<style>
  /* @import rule is removed */
</style>

Gmail strips all external <link> stylesheet references and all @import rules inside <style> blocks. Every style must be in an inline <style> block or in a style attribute.

The 8,192-character style block limit

This is the one that catches people off guard. If a single <style> block in your email exceeds 8,192 characters, Gmail removes the entire block. Not the overflow - the whole thing. Every rule in that block disappears.

<!-- What you wrote -->
<style>
  /* ... 8,193 characters of perfectly valid CSS ... */
</style>

<!-- What Gmail renders -->
<!-- The entire <style> block is gone. -->

Most email developers do not know this limit exists. If you are using a CSS framework, a design system, or generating styles programmatically, it is easy to hit. The fix is to split your styles across multiple <style> blocks, each under the limit.

Outlook Is Even Worse

If Gmail's sanitizer is aggressive, Outlook's Word rendering engine is hostile. Outlook desktop (2016, 2019, 2021) strips everything Gmail strips, plus:

border-radius - no rounded corners, period. Your carefully rounded buttons become rectangles.
display: flex - Gmail keeps it, Outlook removes it. Flexbox does not exist in Word.
background-size - background images render, but you cannot control their sizing.
max-width and min-width - width constraints are unreliable. Use fixed width instead.
float - the traditional CSS layout fallback does not work either.

The reason is straightforward: Microsoft Word's HTML renderer was built for converting Word documents to HTML, not for rendering modern web pages. It supports a subset of HTML 4 and CSS 2, and that is roughly where it stops.

There is good news on the horizon. Microsoft is rolling out a new Chromium-based Outlook that uses a proper browser engine. But the transition is gradual - classic Word-engine Outlook and new Chromium Outlook coexist, and you need to support both for the foreseeable future.

Dark Mode: The Wild West

If cross-client CSS support is a mess, dark mode is where it becomes genuinely chaotic. Every email client handles dark mode differently, and there is no single approach that works everywhere.

Gmail web desktop: Does NOT transform email content at all. It darkens the surrounding Gmail UI chrome, but your email renders exactly as written - light background and all.
Gmail iOS: Full colour inversion. It applies a CSS filter that inverts colours across the entire email body, then re-inverts images so photos do not look like negatives.
Outlook desktop (Word engine): Partial inversion with per-element colour replacement. It selectively replaces background and text colours, sometimes producing unexpected combinations.
Outlook.com / New Outlook: Partial inversion at a lower intensity, closer to a colour remap than a true invert.

The practical consequence is that an email can look correct in Gmail web dark mode (because nothing changes), broken in Gmail iOS dark mode (because your dark-on-dark section disappears), and weird in Outlook (because it replaced your brand green with a shade of teal it thought was more readable).

There is no CSS property or meta tag that reliably controls dark mode across all clients. You have to test each one.

Gmail vs Outlook: CSS Property Comparison

Here is a quick reference for what survives and what does not in the two most common email clients:

CSS Property	Gmail Web	Outlook (Word Engine)
`color`, `background-color`	Supported	Supported
`font-size`, `font-weight`, `font-family`	Supported	Supported
`margin`, `padding`	Supported	Supported
`border`	Supported	Supported
`width`, `height`	Supported	Supported
`text-align`, `vertical-align`	Supported	Supported
`display: block/inline/none`	Supported	Supported
`display: flex`	Supported	Stripped
`align-items`, `justify-content`	Stripped	Stripped
`display: grid`	Stripped	Stripped
`border-radius`	Supported	Stripped
`max-width`, `min-width`	Supported	Stripped
`float`	Supported	Stripped
`background-size`	Supported	Stripped
`box-shadow`	Stripped	Stripped
`position` / offsets / `z-index`	Stripped	Stripped
`transform`	Stripped	Stripped
`animation`, `transition`	Stripped	Stripped
`@font-face`	Stripped	Stripped
`@media` queries	Stripped	Stripped
`@import` / external stylesheets	Stripped	Stripped

The pattern is clear: Outlook strips everything Gmail strips, plus border-radius, display: flex, background-size, max-width/min-width, and float. If it works in Outlook, it works everywhere.

How to Catch This Before Your Users Do

I got tired of sending test emails to myself, opening them in six different clients, and squinting at screenshots. So I built a tool to solve it.

@mailpeek/preview is a Vue component that previews how Gmail and Outlook render your email HTML. It runs the same kind of CSS filtering those clients perform - stripping unsupported properties, removing @media queries, enforcing the style block character limit - and shows you the result in real time.

Install it:

npm install @mailpeek/preview

Drop it into any Vue 3 app:

<script setup lang="ts">
import { EmailPreview } from '@mailpeek/preview'
import '@mailpeek/preview/style.css'

const emailHtml = `
  <html>
    <head>
      <style>
        .hero { border-radius: 8px; box-shadow: 0 2px 8px rgba(0,0,0,0.1); }
        .cta { display: flex; align-items: center; justify-content: center; }
      </style>
    </head>
    <body>
      <div class="hero">
        <h1>Welcome aboard</h1>
        <div class="cta">
          <a href="#">Get Started</a>
        </div>
      </div>
    </body>
  </html>
`
</script>

<template>
  <!-- Gmail mode: box-shadow stripped, flex sub-properties stripped -->
  <EmailPreview :html="emailHtml" client="gmail" />

  <!-- Outlook mode: all of the above PLUS border-radius stripped -->
  <EmailPreview :html="emailHtml" client="outlook" />
</template>

Switching between client="gmail" and client="outlook" shows you exactly what each client strips. The component also exposes:

A compatibility score (0-100) that tells you how much of your CSS survives in each client. A score of 100 means nothing is stripped. A score of 60 means you have problems.
Console warnings that name every stripped property, where it was found, and why it was removed.
A built-in accessibility checker running 10 WCAG-relevant checks - missing alt text on images, broken heading hierarchy, vague link text, and more.
Dark mode preview that simulates Gmail's no-op behaviour, Outlook's partial inversion, and full colour inversion for iOS clients.
Device width toggles between mobile, tablet, and desktop viewports.

Disclaimer: It is not a pixel-perfect simulation - it approximates client behaviour based on documented CSS restriction databases and community testing from caniemail.com. But it catches the vast majority of issues before you send.

Build Emails That Survive Gmail

Previewing is half the problem. The other half is writing email HTML that works in the first place.

If you have used React Email, you know the idea: instead of writing raw <table> HTML with inline styles by hand, you use components that output email-safe markup. @mailpeek/components is the Vue equivalent.

npm install @mailpeek/components

Here is a welcome email built with mailpeek components:

<script setup>
import {
  EmailHtml, EmailHead, EmailBody, EmailContainer,
  EmailHeading, EmailText, EmailButton, EmailImage,
} from '@mailpeek/components'
</script>

<template>
  <EmailHtml>
    <EmailHead title="Welcome to Acme" />
    <EmailBody>
      <EmailContainer>
        <EmailImage
          src="https://acme.com/logo.png"
          alt="Acme logo"
          width="120"
        />
        <EmailHeading as="h1">Welcome aboard</EmailHeading>
        <EmailText>
          Thanks for creating your account. We are excited to have you.
        </EmailText>
        <EmailButton href="https://acme.com/dashboard">
          Go to Dashboard
        </EmailButton>
      </EmailContainer>
    </EmailBody>
  </EmailHtml>
</template>

Every component outputs table-based HTML with inline styles - the format that survives every email client. EmailContainer becomes a centred <table>, EmailButton becomes a padded <a> inside a <td> with a background colour, EmailColumn becomes table cells with proper valign attributes. You write clean Vue templates; the components handle the ugly-but-compatible output.

When you are ready to send, render the template to an HTML string on the server:

import { render } from '@mailpeek/components'
import WelcomeEmail from './WelcomeEmail.vue'

const html = await render(WelcomeEmail, { name: 'Jane' })
// html is a complete email HTML string
// Send with Resend, SendGrid, Nodemailer, or whatever you use

The render function uses Vue's server-side rendering pipeline to produce a complete HTML document. Pass it to any email sending service as the HTML body.

There are 14 components in total: EmailHtml, EmailHead, EmailBody, EmailContainer, EmailSection, EmailRow, EmailColumn, EmailHeading, EmailText, EmailButton, EmailImage, EmailLink, EmailDivider, and EmailPreviewText. Enough to build most transactional and marketing emails without dropping down to raw table markup.

Wrap-up

Email client rendering is genuinely difficult. The CSS restrictions are inconsistent, poorly documented, and changing as Microsoft transitions Outlook to a new engine. Dark mode multiplies the problem. Testing has historically meant sending real emails and checking them in real clients.

Both @mailpeek/preview and @mailpeek/components are free, open source, and MIT licensed. Vue 3 only, zero runtime dependencies, full TypeScript support.

npm: @mailpeek/preview and @mailpeek/components
Docs: mailpeek.dev
GitHub: github.com/mailpeek/mailpeek
Live demo: mailpeek.dev/demo

If you have ever sent an email that looked perfect in your browser and broken in your inbox, give it a try. And if you find CSS restrictions that the filtering misses, open an issue - the restriction databases are just TypeScript objects and they are straightforward to contribute to.

The Complete Guide to Email Client Rendering Differences in 2026

Mailpeek — Sun, 22 Feb 2026 20:05:10 +0000

If you've ever sent a perfectly crafted HTML email only to discover it looks like abstract art in Outlook, you're not alone. Every email client renders HTML and CSS differently, and in 2026 the landscape is more fragmented than ever.

This guide covers what actually works (and what breaks) across Gmail, Outlook, Apple Mail, Yahoo Mail, and Samsung Mail, with specific CSS support data, dark mode behaviour, and the workarounds that actually solve these problems.

The Core Problem: There Is No Standard

Web browsers have largely converged on standards. Email clients have not.

The reason is simple: email clients are not browsers. Gmail renders your HTML inside its own DOM and aggressively sanitises your CSS. Outlook desktop uses Microsoft Word's HTML engine to render emails. Apple Mail uses WebKit. Yahoo Mail has its own quirks that have persisted for years.

The result is that an email with perfectly valid HTML and CSS will render differently across every client. There is no "write once, render everywhere" for email.

Here's the current state of play.

Gmail: The Strict Sanitiser

Market share: ~31% globally (2025)

Gmail is the second largest email client and arguably the most frustrating to develop for. It aggressively strips CSS it doesn't like, and it "doesn't like" a lot.

What Gmail Strips

External stylesheets (<link rel="stylesheet">) are completely removed
@import rules are completely removed
@font-face is removed (except Roboto and Google Sans)
CSS positioning (position, top, right, bottom, left, z-index) is stripped
Flexbox sub-properties (align-items, justify-content, flex-direction, flex-wrap) are stripped, though display: flex itself is kept
CSS Grid (display: grid, grid-template-columns, etc.) is stripped entirely
Transforms, animations, transitions are all stripped
box-shadow, filter, clip-path, backdrop-filter are stripped
background-image inside <style> blocks strips the entire style block, not just that rule

What Gmail Keeps

Standard box model: margin, padding, width, height, border
background-color, color
font-family, font-size, font-weight, font-style
text-align, text-decoration, line-height
display: block, display: inline-block, display: flex (the property, not sub-properties)
border-radius
max-width

The Style Block Gotchas

Gmail's <style> block handling has several traps:

One syntax error nukes everything. A single unclosed bracket or invalid property causes Gmail to strip your entire <style> block. It does not partially parse; it's all or nothing.
8,192 character limit. If your CSS exceeds 8,192 characters, the entire block is removed. Minify aggressively.
background-image contamination. If any rule in your <style> block contains background-image: url(...), Gmail strips the entire block. Use inline styles for background images.
Class name rewriting. Gmail prefixes your class names with its own namespace. This doesn't break anything by itself, but it means you can't rely on JavaScript-based class targeting.

Gmail's 102KB Clipping

When the raw HTML source exceeds approximately 102KB, Gmail clips the email and shows a "Message clipped" link. Everything beyond the threshold is hidden.

This includes all HTML, inline CSS, text content, and tracking URLs, but not externally hosted images. Keep total HTML under 100KB.

Media Queries

Gmail Web (desktop): Does NOT support media queries
Gmail Mobile (iOS/Android): Supports media queries

This means responsive breakpoints only work on mobile Gmail. Desktop Gmail ignores them entirely.

Outlook: The Word Processor That Renders Email

Market share: ~4% globally, but dominant in enterprise environments

Outlook is actually four different rendering engines wearing the same brand name. In 2026, you need to care about all of them because Microsoft is in the middle of a multi-year migration.

Classic Desktop Outlook (Word Engine: 2007-2021+)

This is the notorious one. Classic Outlook uses Microsoft Word's HTML rendering engine, the same Word that renders your .docx files. It was never designed for modern CSS.

What does NOT work:

display: flex and display: grid are completely ignored
border-radius is ignored (everything is square)
background-image via CSS is ignored (requires VML workaround)
max-width and min-width are ignored
position, float are ignored
CSS animations, transforms, transitions are ignored
Media queries are ignored
Web fonts fall back to Times New Roman (not your next font in the stack; it skips everything)
padding on <p> and <div> is inconsistent
<div> width/height is ignored (divs become 100% width)

What DOES work:

Table-based layouts (<table>, <tr>, <td>)
width and height as HTML attributes on tables/cells
background-color
border (solid only)
text-align
color and basic font properties (system fonts only)

The DPI Scaling Bug

On Windows machines with display scaling above 100% (common on high-resolution laptops), Outlook converts CSS px values to pt inconsistently. HTML attributes stay as pixels, but CSS pixels get distorted, causing layouts to break.

Fix: Add this to your <head>:

<!--[if gte mso 9]>
<xml>
  <o:OfficeDocumentSettings>
    <o:AllowPNG/>
    <o:PixelsPerInch>96</o:PixelsPerInch>
  </o:OfficeDocumentSettings>
</xml>
<![endif]-->

Conditional Comments and Ghost Tables

MSO conditional comments () let you write HTML that only classic Outlook sees. Other clients treat them as regular comments and ignore them.

The most common use is ghost tables: table structures that wrap your <div>-based layout so Outlook doesn't collapse it:

<!--[if mso]>
<table role="presentation" width="600"><tr><td>
<![endif]-->

<div style="max-width: 600px;">
  <!-- Your modern HTML here -->
</div>

<!--[if mso]>
</td></tr></table>
<![endif]-->

VML Background Images

Since Outlook ignores CSS background-image, you need VML (Vector Markup Language) for background images:

<!--[if mso]>
<v:rect xmlns:v="urn:schemas-microsoft-com:vml" fill="true" stroke="false"
  style="width:600px;height:400px;">
  <v:fill type="tile" src="https://example.com/bg.jpg" />
  <v:textbox>
<![endif]-->
  <div style="background-image: url('https://example.com/bg.jpg');">
    Content here
  </div>
<!--[if mso]>
  </v:textbox>
</v:rect>
<![endif]-->

New Outlook for Windows (Chromium-Based)

The new Outlook uses a Chromium-based rendering engine and is essentially the same as Outlook.com. It supports flexbox, media queries, background images, border-radius, web fonts, and modern CSS.

Crucially, it does NOT support MSO conditional comments. They're treated as regular comments and ignored. This means your ghost tables and VML workarounds for classic Outlook are harmlessly invisible in the new Outlook.

The 2025-2026 Transition Timeline

January 2025: Business Standard/Premium users auto-migrated to new Outlook
April 2026: Enterprise users begin migration
October 2026: End of support for Word rendering engine
2029+: Classic Outlook still supported for non-rendering features

This means 2025-2026 is peak dual-Outlook pain. You must code for both the Word engine AND Chromium simultaneously. The good news: conditional comments make this possible without either version seeing the other's workarounds.

Apple Mail: The Gold Standard

Market share: 48-53% globally (the largest email client)

Apple Mail uses WebKit (Safari's engine) and is by far the most standards-compliant email client. If it works in a browser, it probably works in Apple Mail.

What's Supported

Essentially everything: flexbox, grid, media queries, border-radius, background images, transforms, CSS animations (with -webkit- prefix), @font-face web fonts, <link> external stylesheets, @import, and even inline SVG (partial).

Apple Mail scores highest on the Can I email scoreboard across 303 tested features.

Dark Mode Done Right

Apple Mail is the only major client that gives developers full control over dark mode:

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

:root {
  color-scheme: light dark;
}

@media (prefers-color-scheme: dark) {
  .email-body {
    background-color: #1a1a1a;
    color: #e0e0e0;
  }
}

Without the color-scheme declarations, Apple Mail won't apply your custom dark mode styles and may apply its own inversion instead.

Yahoo Mail: The Quirky One

The `height` to `min-height` Bug

Yahoo Mail converts height to min-height. This breaks responsive image patterns where you set height: auto in a media query. It becomes min-height: auto, which is invalid CSS and does nothing.

The `!important` Spacing Bug

This one is subtle:

/* This works: */
display:none!important

/* This does NOT work (note the space): */
display:block !important

If there's a space before !important, Yahoo strips it. No space = keeps it.

CSS Under Comments

Yahoo Mail removes any CSS declarations that appear below HTML comments in your <style> blocks. Keep your comments out of your stylesheets.

Dark Mode

Yahoo Mail applies dark mode to its UI but does not invert email content colours. Your email renders as-is regardless of the user's dark mode setting. This is actually the easiest client to deal with for dark mode.

Samsung Mail: The Wild Card

Samsung Mail's biggest quirk is its auto-fit content feature. It uses HTML width attributes (not CSS width) to determine the email's viewport width. An image with width="600" will force Samsung to render at 600px wide, potentially breaking your responsive layout.

Fix: Always use width="100%" as the HTML attribute on images and wrapper tables.

Other gotchas:

margin works on <p> and headings but not on <div> or <table>
max-width works on <div> and <table> but not on <td>
CSS transitions work; keyframe animations do not
Account type matters: If the Samsung Email app is configured with an Outlook/Exchange account, rendering changes significantly, including loss of media query support

The Dark Mode Matrix

Dark mode is the single most inconsistent feature across email clients. Here's the reality:

Client	What Happens	Can You Control It?
Apple Mail	Respects `@media (prefers-color-scheme: dark)`	Yes, full control
Outlook Mac	Respects `@media (prefers-color-scheme: dark)`	Yes, full control
Thunderbird	Respects `@media (prefers-color-scheme: dark)`	Yes, full control
Gmail Web	Does nothing to email content	N/A
Gmail iOS	Full automatic colour inversion	No
Gmail Android	Partial automatic colour inversion	No
Outlook Desktop (Word)	Full automatic inversion with `!important` overrides	No
Outlook.com / New Outlook	Partial inversion with injected overrides	No
Yahoo Mail	Does not invert email content	N/A

Practical advice: Use off-whites (#FAFAFA) instead of pure white and dark greys (#222222) instead of pure black. Pure #FFFFFF and #000000 trigger the most aggressive inversion in Gmail and Outlook. Slight variations reduce the visual impact of forced inversion.

The CSS Support Cheat Sheet

Feature	Gmail	Outlook (Word)	Apple Mail	Yahoo
`<style>` blocks	Yes (with limits)	Limited	Yes	Yes
External stylesheets	No	No	Yes	No
Media queries	Mobile only	No	Yes	Partial
Flexbox	`display:flex` only	No	Yes	No
Grid	No	No	Yes	No
`border-radius`	Yes	No	Yes	Partial
`background-image` (CSS)	Inline only	No (needs VML)	Yes	Yes
`max-width`	Yes	No	Yes	Yes
Web fonts	Roboto only	No (Times New Roman fallback)	Yes	Partial
CSS animations	No	No	Yes (`-webkit-`)	No
`box-shadow`	No	No	Yes	No

Practical Recommendations

1. Start with Tables, Enhance with CSS

The only layout method that works everywhere is <table>. Build your core layout with tables, then use CSS for enhancement:

<table role="presentation" width="100%" cellpadding="0" cellspacing="0">
  <tr>
    <td style="padding: 20px; background-color: #ffffff;">
      <!-- Content here -->
    </td>
  </tr>
</table>

2. Inline Your Critical Styles

Gmail, Outlook, and Yahoo all handle <style> blocks differently. The only CSS delivery method that works identically everywhere is inline styles. Use a CSS inliner tool as part of your build process.

3. Test Before You Send

The rendering differences are too numerous to catch by eyeballing HTML in a browser. Use a preview tool that simulates how each client will actually render your email, including CSS stripping, dark mode inversion, and responsive behaviour.

Tools like mailpeek let you preview Gmail and Outlook rendering directly in your development environment, with dark mode simulation and compatibility scoring that flags unsupported CSS before you send.

4. Design for Degradation

Your email should look good in Apple Mail and acceptable in Outlook. Don't fight Outlook's limitations; design around them:

Use solid colour backgrounds instead of gradients
Use border-based buttons instead of border-radius pills
Include alt text styled with font-size, color, and font-family so emails are readable with images blocked

5. Watch the Outlook Transition

2026 is the last year you need to worry about the Word rendering engine in new Outlook deployments. But enterprise environments move slowly, so expect to support it through 2027-2028 at minimum. Keep your ghost tables and VML workarounds in place for now.

Building a Gmail/Outlook email preview component for Vue

Mailpeek — Fri, 20 Feb 2026 07:56:21 +0000

If you have ever built transactional emails in a Vue app, you have probably hit the same wall. You write the HTML, send a test, open it in Gmail, and half your styling is gone. Then you open it in Outlook and it looks like it was rendered in 2003.

The React ecosystem has react.email, which gives you components, a preview server, and a whole development workflow. Vue has nothing equivalent. There is a thin wrapper around Unlayer that requires an account, an abandoned MJML builder with zero dependents on npm, and a lot of Stack Overflow threads telling you to just use Litmus.

I'm on a mission to improve this workflow for Vue developers, starting with @mailpeek/preview.

What it does

It is a single Vue 3 component that renders your email HTML in an isolated iframe, simulating how Gmail and Outlook actually handle it, including their CSS restrictions.

npm install @mailpeek/preview


  <script setup lang="ts">
  import { EmailPreview } from '@mailpeek/preview'
  import '@mailpeek/preview/style.css'
  </script>

  <template>
    <EmailPreview :html="yourEmailHtml" />
  </template>

You get a Gmail chrome preview, a client switcher, a mobile and desktop toggle, and metadata extraction including subject line, preheader text, and file size, all out of the box.

How the CSS filtering works

The biggest challenge was simulating what each email client actually does to your CSS.

Gmail strips a surprising amount. No position, no transform, no animation, no box-shadow, no CSS Grid, no flexbox sub-properties. It also strips external stylesheets and @import rules entirely.

Outlook desktop (the Word engine versions from 2016 to 2021) is worse. Everything Gmail strips, plus border-radius, display: flex, background-size, max-width, and min-width.

Mailpeek processes your HTML through a CSS filter before rendering it in the iframe. If your email uses border-radius: 8px and you switch to Outlook mode, the property is stripped and a warning appears in the console:

[mailpeek] Outlook: removed "border-radius: 8px" — Outlook Word renderer does not support border-radius

The filter is regex-based with no DOM dependency, making it fully SSR-safe and compatible with Nuxt 3. The restriction lists are sourced from the Google Developers Gmail CSS documentation and caniemail.com.

What it does not do yet

It is not a replacement for Litmus or Email on Acid. It will not catch every rendering quirk, it does not simulate VML for Outlook, and it does not account for every edge case in every client version. Think of it as a linter that catches obvious issues during development rather than a screenshot testing service.

Dark mode simulation for Gmail, Apple Mail, and Outlook is the next thing on the roadmap.

Try it out!

Live Demo · GitHub

npm install @mailpeek/preview

Zero runtime dependencies beyond Vue 3. TypeScript types included.

If you build HTML emails in Vue and have thoughts on what is missing, I would love to hear them in the comments or as a GitHub issue.

Instagram #pride rainbow tag - how did they do it?

Mailpeek — Fri, 28 Jun 2019 17:22:20 +0000

I noticed this nice touch for pride week and wanted to see if there was anything special about how it was done by the devs at instagram. Turns out there wasn't anything special but it looks great and is really simple to do so decided to write it up anyway!

The main property required here is background-clip. It allows you to clip (or mask) an element or text to it's background image or colour.

Important - in order to apply it to text it still requires the -webkit prefix for Chrome, Firefox, Safari and Edge. In Safari it can't be applied to the button tag but you could get around this with a span!

The rainbow is just a simple png repeated as a background image on the element with the background size increased.

Finally they've set the color of the text to transparent to allow the rainbow background to be visible. Interestingly they used the -webkit-text-fill-color property to do this as the standard color property doesn't allow for the transparent value. The two properties are essentially the same, but -webkit-text-fill-color will take precedence over color if the two have different values. This is useful as it means it will just gracefully fallback to the default colour of the text if not supported.

Here's a quick codepen of the final effect. Anyone got any other more advanced examples of background-clip?

Headless CMS - what are the cool kids using?

Mailpeek — Sun, 23 Jun 2019 17:50:58 +0000

I'm going to make use of my "time" on maternity and finally get a programming blog together, mainly as a way for me to keep up by writing articles on topics I want to brush up on. I've used Kentico cloud for large scale multisites and find it great but are there any others that might suit a personal blog better? I've been looking at Sanity which looks great and really easy to set up, anyone any experience with it?

DEV Community: Mailpeek

Dark Mode is still breaking your HTML emails. Here is the logic to fix it.

Dark Mode in Email: Why Every Client Does It Differently

The Three Dark Mode Strategies

Strategy 1: No transformation

Strategy 2: Full colour inversion

Strategy 3: Partial inversion

What Each Client Actually Does

Gmail Web Desktop: Nothing

Gmail iOS: Full Inversion

Outlook Desktop (Word Engine): Selective Replacement

Outlook.com / New Outlook: Lighter Touch

Apple Mail: Color Scheme Aware

The Comparison Table

Practical Advice

Do not rely on a single dark mode test

Use solid backgrounds on images

Avoid relying on pure white and pure black

Test your dark-on-dark sections

Keep critical information in text, not in styled containers

Preview Before You Send

Why Gmail Breaks Your Email CSS (and How to Catch It Before Your Users Do)

What Gmail Actually Strips

@font-face - gone entirely

@media queries - ignored on desktop

Positioning properties - all stripped

CSS Grid - stripped (but flexbox partially survives)

Visual effects - stripped

External stylesheets and @import - stripped

The 8,192-character style block limit

Outlook Is Even Worse

Dark Mode: The Wild West

Gmail vs Outlook: CSS Property Comparison

How to Catch This Before Your Users Do

Build Emails That Survive Gmail

Wrap-up

The Complete Guide to Email Client Rendering Differences in 2026

The Core Problem: There Is No Standard

Gmail: The Strict Sanitiser

What Gmail Strips

What Gmail Keeps

The Style Block Gotchas

Gmail's 102KB Clipping

Media Queries

Outlook: The Word Processor That Renders Email

Classic Desktop Outlook (Word Engine: 2007-2021+)

The DPI Scaling Bug

Conditional Comments and Ghost Tables

VML Background Images

New Outlook for Windows (Chromium-Based)

The 2025-2026 Transition Timeline

Apple Mail: The Gold Standard

What's Supported

Dark Mode Done Right

Yahoo Mail: The Quirky One

The height to min-height Bug

The !important Spacing Bug

CSS Under Comments

Dark Mode

Samsung Mail: The Wild Card

The Dark Mode Matrix

The CSS Support Cheat Sheet

Practical Recommendations

1. Start with Tables, Enhance with CSS

2. Inline Your Critical Styles

3. Test Before You Send

4. Design for Degradation

5. Watch the Outlook Transition

Further Reading

Building a Gmail/Outlook email preview component for Vue

What it does

Instagram #pride rainbow tag - how did they do it?

Headless CMS - what are the cool kids using?

The `height` to `min-height` Bug

The `!important` Spacing Bug