Skip to content

Instantly share code, notes, and snippets.

@tomholford

tomholford/email-styling-best-practices.md

Last active March 5, 2026 00:06
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save tomholford/b69d730a653639537018af7686b89b07 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save tomholford/b69d730a653639537018af7686b89b07 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
email-styling-best-practices.md

Email Styling Best Practices

Email rendering is fundamentally different from web rendering. There is no universal standard — each email client uses its own engine, strips different things, and handles dark mode differently. This guide is split into two parts: design principles for designers, and technical reference for developers.

Part 1: Design Principles

For designers who may not be familiar with email-specific constraints.

The Mental Model

Design emails like a poster, not a web page. Simple layout, system fonts, high contrast, no interactivity. If your design still communicates clearly as plain text with colored blocks, it will survive any email client.

Email clients are not browsers. Outlook desktop uses Microsoft Word's HTML engine. Gmail aggressively strips CSS. Apple Mail uses WebKit. Yahoo has its own quirks. A pixel-perfect design in one client can break completely in another.

Layout

Width

  • Design for 600px max width. This is the universally safe content width. Wider layouts risk clipping or horizontal scrolling in preview panes.
  • Many users read email in narrow preview panes (300–400px), so critical content should work at small sizes too.

Structure

  • Single-column layouts are the safest and degrade most gracefully across devices. Use them for most emails, especially text-heavy content.
  • Multi-column layouts (2–3 columns max) are possible but must be designed to stack vertically on mobile. Don't rely on columns staying side-by-side.
  • Avoid complex grids. If your layout needs more than 2–3 columns, simplify it.

Spacing

  • Use generous padding inside content blocks — this is the most reliable spacing method.
  • Margins between elements are inconsistent across clients. Think of spacing as padding within containers, not gaps between elements.
  • Give content room to breathe. White space improves readability and reduces cognitive load.

Typography

Font Selection

  • Use web-safe/system fonts: Arial, Helvetica, Georgia, Verdana, Tahoma, Times New Roman, Trebuchet MS.
  • Custom web fonts (Google Fonts, Adobe Fonts) only work in Apple Mail and a handful of others. Every other client falls back to a system default. Always choose a fallback font that preserves your design intent.

Sizing

  • Body text: 14–16px minimum. Some mobile clients enforce a minimum size and will auto-enlarge small text, breaking your layout.
  • Headlines: 22–28px — large enough to be scannable.
  • Line height: 1.4–1.6× the font size for comfortable reading.
  • Keep paragraphs short. Emails are skimmed, not read.

Color & Dark Mode

Dark Mode Is Not in Your Control

Over 80% of users have dark mode enabled on at least one device. Email clients handle it in three different ways:

Behavior What Happens Clients
Full inversion All colors reverse — backgrounds, text, buttons Outlook desktop (Windows), Yahoo Mail
Partial inversion Backgrounds darken, text lightens, images preserved Gmail mobile, Outlook web/Mac/mobile
No change Email renders as designed Gmail web, Apple Mail (partially), AOL

Your carefully chosen palette may be transformed without your consent.

Color Guidelines

  • Avoid pure white (#ffffff) backgrounds — use off-white (#fefefe, #f8f8f8). Pure white can get force-inverted to pure black.
  • Avoid pure black (#000000) text — use near-black (#1a1a1a, #333333). Same reason.
  • Ensure sufficient contrast in both light and dark contexts.
  • Don't rely on color alone to convey meaning (e.g., red = error). Use text labels too.
  • Follow WCAG AA contrast ratios: 4.5:1 for body text, 3:1 for large text and UI elements.

Images

Assume Images Will Be Hidden

Many clients (especially corporate Outlook) block images by default until the user clicks "Show images." Design so the email still makes sense with no images visible — just text and colored blocks.

  • Never put critical information only in images (prices, dates, CTAs, key messaging).
  • Every image needs meaningful alt text — it's the only thing visible until images load.

Logo Handling for Dark Mode

  • Transparent PNGs with dark logos will vanish on dark backgrounds. Add a subtle border, glow, or use a version with a built-in background.
  • Consider providing alternate logo versions for dark contexts.

General Image Guidelines

  • Use 2x resolution for retina, but set display dimensions at 1x.
  • Keep file sizes small — large images slow load times on mobile.
  • Animated GIFs work in most clients. Outlook on Windows shows only the first frame — make it meaningful.
  • SVG is unreliable. Use PNG or JPEG.
  • Video and audio cannot be embedded. Use a thumbnail image linking to the hosted video.

Buttons & Calls to Action

Design

  • Make buttons large and tappable — at least 44×44px touch target for mobile.
  • Use solid background colors, not image-based buttons (images may be blocked).
  • Rounded corners don't work in Outlook on Windows. Design buttons that still look intentional as sharp rectangles.
  • Button text must be live text, not text-as-image.

Placement

  • Place primary CTA above the fold (visible without scrolling).
  • One clear primary action per email. Don't compete for attention with multiple equal-weight CTAs.
  • Repeat important CTAs at the end if the email is long.

Preheader Text

The preheader is the short summary text that appears after the subject line in the inbox list view. It's your second chance (after the subject line) to convince someone to open the email.

  • Keep it 40–130 characters (varies by client and device).
  • Make it complement the subject line, not repeat it.
  • If you don't set it, the client will pull the first text from the email body — which might be "View in browser" or an alt tag.

Accessibility

Per the Email Markup Consortium's 2025 report, 99.89% of emails have accessibility issues rated "Serious" or "Critical." This is an area where even basic effort puts you ahead.

  • Use real text, not text-as-image. Screen readers can't read images.
  • Maintain high color contrast (WCAG AA minimums).
  • Use heading hierarchy (H1 → H2 → H3) — screen readers use headings for navigation.
  • Link text must be descriptive ("View your order" not "Click here").
  • Don't rely on color alone to convey information.
  • Ensure the email reads logically when linearized (single-column, top-to-bottom).

What You Cannot Use

Feature Why
Flexbox / CSS Grid Ignored by Outlook and many webmail clients
Absolute/fixed positioning Not supported
Hover/focus effects Only Apple Mail + a few others
Animations / transitions Very limited support
Video / audio embeds Blocked for security
Interactive forms, carousels Don't function reliably
JavaScript Stripped by all clients
Background images Outlook ignores them
Box shadows Inconsistent

Design Checklist

Before handing off to development:

  • Layout is ≤600px wide
  • Works as single-column (or columns stack gracefully)
  • Uses only web-safe fonts (with fallbacks chosen)
  • No critical info is image-only
  • Alt text provided for every image
  • Buttons look good as sharp rectangles (no border-radius dependency)
  • Readable in both light and dark mode
  • No pure white backgrounds or pure black text
  • Logos work on dark backgrounds (no vanishing transparent PNGs)
  • Preheader text is set and complements the subject line
  • Primary CTA is above the fold
  • Color contrast meets WCAG AA (4.5:1 body, 3:1 large text)
  • Total design complexity is low (few sections, simple structure)

Part 2: Technical Reference

For web developers implementing email templates.

Rendering Engine Landscape (2026)

Client Rendering Engine Key Limitations
Outlook (Windows desktop) Microsoft Word HTML engine No flexbox/grid, no background images, no border-radius, limited CSS
Gmail (web) Custom DOM + aggressive CSS sanitization Strips <style> in <head>, prefixes/renames classes, 102KB clip
Gmail (mobile app) Varies by platform Supports <style> blocks, partial dark mode inversion
Apple Mail (macOS/iOS) WebKit Best CSS support — closest to a real browser
Outlook.com (web) Custom rendering Strips some CSS, partial dark mode support
Yahoo Mail Custom rendering Full dark mode inversion, strips some CSS
Samsung Mail WebKit-based Generally good support, dark mode quirks

Core Constraints

Inline Styles Are Required

  • Gmail web strips <style> tags from <head>. Inline style="" on every element is the only universally safe approach.
  • Use a CSS inliner tool during build (e.g., Juice, Premailer, MJML's built-in inliner) to author with classes and inline at build time.
  • If you include a <style> block for progressive enhancement, put it after inline styles so clients that support both get the enhanced version.

Table-Based Layout

  • Use <table>, <tr>, <td> for all structural layout. Flexbox and grid are not options.
  • Set role="presentation" on all layout tables so screen readers don't announce them as data tables.
  • Always set cellpadding="0", cellspacing="0", border="0" on tables to reset defaults.
  • Use width attributes on <table> and <td> elements (HTML attributes, not just CSS) for Outlook compatibility.

Box Model & Spacing

  • Use padding on <td> for spacing. margin is inconsistent on block elements across clients.
  • Outlook doesn't support padding on <p>, <div>, or <a> reliably — always apply it to <td> cells.
  • For vertical spacing, use empty <tr> with a <td> that has explicit height and font-size: 0; line-height: 0;.

CSS Support Reference

Universally Safe

color, background-color
font-family, font-size, font-weight, font-style
line-height, text-align, text-decoration, text-transform
padding (on <td>)
border, border-collapse
width, height (on <table>, <td>, <img>)
vertical-align

Mostly Safe (Fails in Outlook Desktop)

border-radius
background-image (use VML fallback for Outlook)
box-shadow
max-width (use width + conditional comments)

Unreliable / Avoid

display: flex, display: grid
float (buggy in Outlook)
position: absolute/relative/fixed
margin (inconsistent)
@import
calc()
CSS variables (custom properties)
::before, ::after pseudo-elements
:hover, :focus (Apple Mail only)
animation, transition

Gmail-Specific Issues

  • Gmail web strips <style> blocks — inline everything critical.
  • Gmail clips emails over ~102KB of HTML. Everything past the cutoff is hidden behind "View entire message," including footers and unsubscribe links.
  • Gmail prefixes class names (e.g., .btn becomes .m_12345_btn), which can break CSS selectors that survive the strip.
  • Gmail mobile (app) does support <style> blocks, so embedded styles provide progressive enhancement for Gmail app users.

Dark Mode Implementation

CSS Media Query (Progressive Enhancement)

@media (prefers-color-scheme: dark) {
  .email-body {
    background-color: #1a1a1a !important;
    color: #e0e0e0 !important;
  }
  .email-logo {
    /* Swap to light version of logo */
    content: url('logo-light.png');
  }
}

Support: Apple Mail, Outlook (macOS/iOS), some Gmail app versions. Does NOT work in Gmail web, Outlook Windows desktop, or Yahoo.

Meta Tag for Color Scheme

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

Tells clients that your email supports both modes and discourages forced inversion.

Practical Dark Mode Tips

  • Avoid pure white/black — use off-white (#fefefe) and near-black (#1a1a1a) so forced inversion produces usable results.
  • Add a 1px transparent border around images with white backgrounds to prevent them from blending into inverted dark backgrounds.
  • Use PNG logos with a subtle built-in background or border so they don't vanish on dark backgrounds.
  • Test dark mode in: Apple Mail, Gmail (iOS app), Outlook (Windows + web), Yahoo.

Responsive Email Techniques

Since media query support is inconsistent, use hybrid/fluid coding as the baseline:

Fluid Width (No Media Queries Needed)

<table role="presentation" width="100%" style="max-width: 600px; margin: 0 auto;">

This table is 100% width on small screens, capped at 600px on larger screens. Works without media queries.

Outlook Conditional Comments

Outlook desktop ignores max-width, so wrap fluid tables in conditional comments:

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

<table role="presentation" width="100%" style="max-width: 600px;">
  <!-- content -->
</table>

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

Media Queries (Progressive Enhancement)

@media only screen and (max-width: 600px) {
  .column { width: 100% !important; display: block !important; }
  .hide-mobile { display: none !important; }
  .mobile-padding { padding: 10px !important; }
}

These enhance the experience in clients that support them (Apple Mail, Gmail app, Samsung Mail) but aren't required for basic functionality.

Buttons (Bulletproof)

Table-Based (Works Everywhere Including Outlook)

<table role="presentation" cellpadding="0" cellspacing="0" border="0">
  <tr>
    <td align="center" bgcolor="#1a73e8" style="border-radius: 4px;">
      <a href="https://example.com"
         style="display: inline-block; padding: 12px 24px;
                font-family: Arial, sans-serif; font-size: 16px;
                color: #ffffff; text-decoration: none;">
        Click Here
      </a>
    </td>
  </tr>
</table>

Note: border-radius won't render in Outlook desktop but the button remains fully functional and visually acceptable.

VML Button (Outlook-Specific with Border Radius)

For rounded buttons in Outlook, use VML:

<!--[if mso]>
<v:roundrect xmlns:v="urn:schemas-microsoft-com:vml" href="https://example.com"
  style="height:44px;v-text-anchor:middle;width:200px;" arcsize="10%" fillcolor="#1a73e8">
  <w:anchorlock/>
  <center style="color:#ffffff;font-family:Arial;font-size:16px;">Click Here</center>
</v:roundrect>
<![endif]-->

Accessibility Implementation

  • Set lang attribute on the <html> element.
  • Use role="presentation" on all layout tables.
  • Use semantic headings (<h1>, <h2>, <h3>) — not styled <p> or <span> tags.
  • Add alt text to every <img>. Use alt="" (empty) for purely decorative images.
  • Ensure link text is descriptive — avoid "Click here" or "Read more."
  • Use <th scope="col"> / <th scope="row"> for actual data tables.
  • Don't use display: none to visually hide preheader text — screen readers may skip it. Use the clipping technique:
<span style="display: none; max-height: 0; overflow: hidden; mso-hide: all;">
  Preheader text here
</span>

Preheader Text Implementation

<!-- Visible preheader (hidden visually, shown in inbox preview) -->
<div style="display: none; max-height: 0px; overflow: hidden; mso-hide: all; font-size: 0;">
  Your preheader text goes here (40-130 characters recommended)
</div>
<!-- Prevent Gmail from pulling body text into preview -->
<div style="display: none; max-height: 0px; overflow: hidden; mso-hide: all;">
  &nbsp;&zwnj;&nbsp;&zwnj;&nbsp;&zwnj;&nbsp;&zwnj;&nbsp;&zwnj;&nbsp;&zwnj;&nbsp;&zwnj;
  <!-- Repeat ~100 times to fill preview space -->
</div>

Template Skeleton

<!DOCTYPE html>
<html lang="en" xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <meta name="color-scheme" content="light dark">
  <meta name="supported-color-schemes" content="light dark">
  <!--[if mso]>
  <xml><o:OfficeDocumentSettings><o:PixelsPerInch>96</o:PixelsPerInch></o:OfficeDocumentSettings></xml>
  <style>table { border-collapse: collapse; }</style>
  <![endif]-->
  <title>Email Title</title>
  <style>
    /* Progressive enhancement - these may be stripped */
    @media (prefers-color-scheme: dark) {
      .email-bg { background-color: #1a1a1a !important; }
      .email-text { color: #e0e0e0 !important; }
    }
    @media only screen and (max-width: 600px) {
      .fluid { width: 100% !important; }
    }
  </style>
</head>
<body style="margin: 0; padding: 0; background-color: #f4f4f4; font-family: Arial, sans-serif; -webkit-text-size-adjust: 100%; -ms-text-size-adjust: 100%;">
  <!-- Preheader -->
  <div style="display: none; max-height: 0; overflow: hidden; mso-hide: all; font-size: 0;">
    Preview text here
  </div>

  <!-- Outer wrapper -->
  <table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0" class="email-bg" style="background-color: #f4f4f4;">
    <tr>
      <td align="center" style="padding: 20px 0;">
        <!--[if mso]><table role="presentation" width="600" cellpadding="0" cellspacing="0"><tr><td><![endif]-->
        <table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0" class="fluid" style="max-width: 600px; background-color: #ffffff;">
          <tr>
            <td style="padding: 20px; font-size: 16px; line-height: 1.5; color: #333333; font-family: Arial, sans-serif;" class="email-text">
              <!-- Content here -->
            </td>
          </tr>
        </table>
        <!--[if mso]></td></tr></table><![endif]-->
      </td>
    </tr>
  </table>
</body>
</html>

Build & Testing Tools

Tool Purpose
Can I Email CSS/HTML feature support by client (like caniuse.com for email)
Litmus Cross-client rendering previews (90+ clients)
Email on Acid Cross-client rendering + accessibility checks
MJML Component framework that compiles to compatible HTML
Maizzle Tailwind CSS framework for email, outputs inlined HTML
Juice CSS inliner (Node.js)
Premailer CSS inliner (Ruby)
Email Markup Consortium Standards and accessibility reports
Parcel (by Tilt) Email code editor with real-time previews

Further Reading

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment