You build a signature that looks perfect in Gmail's web app, your CEO opens it in Outlook on Windows, and sees a wall of broken layout, missing images, and wrong fonts. This is the cross-client rendering problem: every major mail client uses a different HTML engine, and a signature that ships needs to survive all of them.
This post covers the nine specific things that break across Gmail, Outlook (desktop and web), and Apple Mail — plus the fix for each.
Why this happens
Mail clients aren't browsers. Gmail's web client renders HTML through its own sanitizer that strips unknown tags. Outlook on Windows uses Microsoft Word as its rendering engine — yes, Word — which has no support for flexbox, grid, or most CSS3. Apple Mail uses WebKit, which is closest to a real browser but still has its own quirks around image sizing and dark mode. The result: a signature can pass three QA checks and break on the fourth.
The fix isn't picking one client and hoping. The fix is designing to the lowest common denominator — table-based HTML with inline styles — and testing in all three.
The 9 things
1. External CSS gets stripped
Gmail and Outlook both strip <link rel="stylesheet"> and most <style> blocks before delivery. Any styling that lives in an external file or a <head> block silently disappears.
Fix: Inline every CSS rule with the style="" attribute on each element. Tools like juice automate this — MailSigCraft inlines all styles by default before you copy.
2. Flexbox and grid don't render in Outlook
Outlook desktop on Windows uses Word's HTML engine, which predates flexbox and grid by a decade. display: flex is silently ignored; the layout collapses to a vertical stack.
Fix: Use <table> elements for every layout decision — multi-column signatures, side-by-side logo and text, all of it. Set cellpadding="0" cellspacing="0" border="0" to remove default table chrome.
3. Images need absolute URLs
Relative paths don't resolve in mail clients. <img src="logo.png"> works in your dev preview and renders as a broken image in every recipient's inbox.
Fix: Every <img> needs a fully-qualified https:// URL. MailSigCraft hosts uploaded images on a CDN automatically. If you're hand-rolling the HTML, use imgix, Cloudinary, or your own static host.
4. Images render at native size on Retina
Apple Mail (macOS and iOS) renders images at native pixel size by default. A 200×200 logo intended for 32px display shows up at 200×200 — comically large.
Fix: Set explicit width="" and height="" attributes on every <img> and export the source asset at 2× the display size (64×64 for a 32px display) for crisp rendering on both Retina and standard screens.
5. Web fonts get replaced with system fallbacks
Custom fonts loaded via <link> or @import are stripped (see #1). Even fonts referenced inline with style="font-family: 'Custom Sans'" fall back to system fonts when the font file isn't bundled — and most clients block font-bundling for security reasons.
Fix: Use a system font stack: font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Arial, sans-serif. The signature renders in the local system font on every device — consistent and crisp.
6. CSS background images don't render in Outlook
background-image: url(...) on a <td> or <div> is silently dropped by Outlook desktop's Word renderer. The cell renders with no background.
Fix: Use a real <img> element instead, or VML fallback for Outlook (<!--[if mso]>...<![endif]--> conditional comments). For signatures specifically, avoid backgrounds entirely — they rarely survive the round-trip.
7. Dark mode inverts colors unpredictably
Gmail iOS and Apple Mail macOS partially auto-invert signatures in dark mode. A logo on a white background may end up on a near-black background, with the original transparent edges suddenly visible as halos.
Fix: Either commit to a transparent-background design that works on both light and dark, or wrap the signature in a <table bgcolor="#ffffff" style="background-color: #ffffff !important;"> to force a white background even in dark mode.
8. Hex shorthand colors break in older Outlook
Outlook 2007–2016 chokes on three-character hex codes like #fff — it interprets them as malformed and falls back to default black. Modern Outlook handles them, but older deployed versions still don't.
Fix: Always use six-character hex (#ffffff, not #fff). Two extra characters per color removes an entire class of legacy rendering failures.
9. Unminified HTML hits Gmail's 10K character limit
Gmail's signature storage caps at 10,000 HTML characters. Pretty-printed, indented HTML is 10–20% larger than minified output, and the overhead adds up — especially with base64-embedded images.
Fix: Minify the final HTML before pasting, host images on a CDN instead of inlining them as base64, and check the character count before pasting. Full breakdown in Why your Gmail signature is being cut off.
The test matrix that catches all nine
If you're rolling your own signatures, test in this order before shipping:
- Outlook desktop (Windows) — the strictest renderer
- Gmail web — the most-used renderer
- Apple Mail macOS — your design lives or dies on this one's dark mode handling
- Gmail iOS app — the most-used mobile renderer
The full install + troubleshoot guides cover the device-specific fixes for each:
Build the signature in the MailSigCraft editor and you skip all nine — every signature is exported as inline-styled, table-based, system-font, CDN-hosted, minified HTML by default. The output paste-tests across all three clients without changes.