Ask any AI coding assistant for an email template and you'll get something beautiful: flexbox layout, border-radius, rgba() colors, a clean <button>. Paste it into your ESP, send a test, open it in Gmail on your phone — perfect.
Then a customer opens it in Outlook on Windows and it looks like a ransom note.
This isn't the AI being dumb. It's the AI being too smart — applying everything it knows about modern web development to a medium where most of that knowledge is actively wrong.
Email clients are not browsers
Here's the fact that breaks everyone's mental model: Outlook for Windows renders HTML email with Microsoft Word's engine. Not a browser engine. Word. The same thing that renders your .docx files.
That one fact cascades into a pile of constraints:
-
No flexbox, no grid, no floats. Layout has to be done with
<table>elements, like it's 2005. -
No
max-width. Your responsive container doesn't constrain anything in Outlook. -
No
border-radius. Your rounded button is a sharp rectangle. - No background images without special VML markup.
-
paddingon a<div>is ignored — only<td>padding is reliable. -
rgba()and 3-digit hex fail. Six-digit hex only.
And Outlook isn't even the only landmine:
- Gmail clips your email at 102KB of HTML. Everything past the cut — including your unsubscribe link and tracking pixel — just vanishes behind a "[Message clipped]" link.
-
Gmail drops your entire
<style>block if a single CSS rule has a syntax error. - Gmail and Outlook mobile force dark mode by inverting your colors, ignoring your media queries.
- Images are blocked by default in Outlook — so your email has to communicate as styled text first.
None of this is in the training data's "best practices for HTML/CSS," because none of it is true for browsers. So the AI confidently generates browser-correct code that fails in the one place corporate email actually gets read.
The patterns that actually work
Email developers have spent fifteen years figuring out the workarounds.
Bulletproof buttons
A CSS button with border-radius is square in Outlook. The fix is a hybrid: a normal anchor for modern clients, plus a VML <v:roundrect> that only Outlook sees, hidden from everyone else inside conditional comments. Rounded corners in Outlook, clean anchor everywhere else, and it works with images blocked because it's real text.
The hybrid (spongy) layout
You want fluid width on modern clients but Outlook needs a fixed pixel width. The trick is a "ghost table" wrapped in <!--[if mso]> that only Outlook sees. Modern clients honor max-width and go fluid; Outlook reads the fixed ghost table and renders correctly.
Dark mode survival
You can't stop Gmail/Outlook mobile from force-inverting colors, but you can design palettes that survive it, and target Outlook.com's dark-mode rewrite with its proprietary [data-ogsc] selectors.
I packaged all of it into a Claude skill
I kept re-explaining these rules to Claude on every email task, so I turned them into a Claude skill — a reusable instruction pack the agent loads automatically when it detects an email task.
It's just a SKILL.md with the non-negotiable rules plus data files: a CSS support matrix for 25+ clients grouped by rendering engine, copy-paste bulletproof patterns (the button, hybrid layout, dark-mode kit, preheader, compliance footer), a pre-send QA checklist, and production templates.
Install is one line:
git clone https://github.com/jayesh-bansal/email-pro-max.git ~/.claude/skills/email-pro-max
After that, when you ask Claude for an email, the first draft uses table layout, VML buttons, styled alt text, and dark-mode-safe colors — instead of browser-correct code that breaks where it matters.
It's MIT, zero dependencies, just markdown. Repo here, with a before/after Outlook comparison in the README:
→ https://github.com/jayesh-bansal/email-pro-max
If you do email development professionally, I'd genuinely love a second pair of eyes on the client-support matrix — open an issue if you catch something it gets wrong.
