| name | email-client-gotchas |
| description | Framework-agnostic reference for HTML email client quirks — Outlook rendering, dark mode, Gmail clipping, image blocking, preheader text, width constraints, font fallbacks. Use whenever authoring, debugging, or reviewing any HTML email regardless of framework. |
Email Client Gotchas
HTML email is ~2005-era HTML. Unlike the web, there is no consistent rendering target. These quirks apply regardless of whether you use Foundation, Maizzle, MJML, or raw tables.
Width and structure
- Max body width: 600px (some go to 640–680). Narrower is safer. Outlook adds chrome that eats horizontal space.
- Layout via
<table> — not divs, not flex, not grid. Frameworks hide this but the output is always tables.
- No position/float — absolute/relative positioning is unreliable. Float works in some clients but not Outlook.
- Nested tables are fine and expected.
Outlook (desktop: 2016/2019/365/Win Mail)
The most fragile target. Uses Word's rendering engine (not a browser).
- No margin on
<p> or <div> — use table cell padding or spacer rows instead.
- No CSS background-images — use VML fallback:
- Buttons: use VML "bulletproof" buttons (Foundation/MJML generate these automatically).
- Line-height: add
mso-line-height-rule: exactly to avoid extra spacing.
- Rounded corners: ignored — accept squared corners in Outlook or provide VML fallback.
- Images: specify width/height as HTML attributes AND inline CSS. Outlook can't handle responsive images via CSS alone.
Gmail
- Clips emails over ~102KB — shows "View entire message" link. Keep compiled+inlined HTML under 100KB.
- Strips
<style> from the <head> on some clients (mobile) — always inline critical CSS.
- Blocks external CSS and JavaScript unconditionally.
- Honors media queries in Gmail app (since 2016) but not always in Gmail Go / older mobile.
- Removes
class attributes in some paths — rely on inlined styles, not classes.
Apple Mail (macOS + iOS)
Yahoo / AOL
- Similar to Gmail. Strips some pseudo-classes. Generally forgiving if inlined.
Dark mode strategy
Three approaches, pick one:
- Embrace inversion — design for light mode, let clients invert. Test logos/images with transparent backgrounds.
- Force light — wrap critical elements with inline background-colors that resist inversion. Fragile.
- Respond — use
@media (prefers-color-scheme: dark) with dark-specific styles. Works in Apple Mail, Outlook.com, some others; ignored elsewhere (which falls back to #1).
Fonts
- Safe web-safe stack:
Arial, Helvetica, sans-serif / Georgia, 'Times New Roman', serif.
- Google Fonts: add
<link> in <head> and @import — works in Apple Mail, iOS, some Android. Outlook ignores, falls back. Always specify a fallback.
- Custom font files: generally don't bother — ROI is low.
Images
- Always set
alt — 40%+ of users have images blocked by default.
- Always set
width and height as HTML attributes (not just CSS).
- Use absolute URLs for
src — relative paths won't work once sent.
- Avoid PNG transparency for logos that sit on dark backgrounds when dark mode inverts — use solid backgrounds or SVG where supported.
- Retina: export 2x, display at 1x (set width/height to half the image's native size).
- No SVG in most clients — use PNG/JPG.
Preheader text
The snippet of text shown next to the subject line in the inbox. Set it explicitly:
<div style="display:none;font-size:1px;color:#ffffff;line-height:1px;max-height:0px;max-width:0px;opacity:0;overflow:hidden;mso-hide:all;">
Your preheader text here — keep under 90 chars
</div>
Without this, clients grab the first visible text, which is usually "View this email in your browser" — wasted real estate.
Links
- Absolute URLs only —
href="https://..." (not href="/page").
- Underline by default — some clients strip
text-decoration: none, so design for underlined links.
- No
target="_blank" guaranteed — clients ignore it.
- Tracked links (via ESP) are rewritten on send — test the final sent version, not just the compiled template.
Forms and interactivity
- No
<form>, no <input>, no <button> submit behavior — stripped or inert.
- No JavaScript — stripped.
- CSS-only interactivity (checkbox hack, hover effects) works in ~30% of clients. Don't rely on it.
- AMP for Email is a separate, opt-in format — ignore unless specifically building for Gmail AMP.
Accessibility
lang="en" on <html>.role="presentation" on layout tables: <table role="presentation" ...>.- Proper heading hierarchy (
<h1> → <h2> etc.).
- Minimum 14px body font, 16px preferred.
- Color contrast ≥ 4.5:1 for body text.
Pre-send checklist
