email-html-mjml — Production-Ready Email Templates for Claude Code

A Claude Code skill that generates responsive, cross-client HTML email from a single conversation.

Describe your email. Get back valid MJML source and compiled, production-ready HTML — guaranteed to render in Outlook 2013–365, Gmail (web and app), and Apple Mail without manual table coding, VML hand-authoring, or email client guesswork.

The Problem: Email Rendering Is Broken by Design

Every major email client uses a different rendering engine:

• Outlook 2007–2021 renders HTML with Microsoft Word — not a browser
• Gmail strips <head> CSS and clips messages over 102KB
• iOS Mail and Android stack multi-column layouts when whitespace exists between inline-block elements
• Apple Mail applies forced dark-mode inversion on light backgrounds

The result: an email that looks correct in a browser can break catastrophically in production. Fixing it requires deep knowledge of VML injection, Ghost Tables, CSS inlining, and client-specific quirks that are rarely documented in one place.

The Solution: MJML as a Reliability Framework

This skill uses MJML 5.x — not as a convenience layer, but as a structural reliability framework. MJML compiles semantic XML into the deeply nested, client-specific table HTML that email clients actually need. The output includes:

• Ghost Tables (MSO conditional comments) that constrain layout for Outlook's Word engine while remaining invisible to modern clients
• Automatic VML injection for background images in <mj-section> and <mj-hero>, the only two components where Outlook supports them
• Hybrid-Fluid column math — fluid percentage widths for modern clients, fixed Ghost Table widths for Outlook — generated from the same source

Writing this HTML by hand is error-prone and nearly impossible to maintain. MJML makes the correct output the default output.

What This Skill Delivers

Gmail Clip Prevention

Every template is compiled with --config.minify=true, keeping compiled HTML under Gmail's 102KB clip threshold — MJML 5's cssnano also minifies CSS, so output is smaller than MJML 4's overall.

Note that in MJML 5 minification no longer removes whitespace between tags (htmlnano collapses each run to a single space). The iOS/Android column stacking bug is prevented by the font-size:0px MJML emits on the parent <td>, not by minification. Pass --config.minifyOptions '{"collapseWhitespace":"all"}' for the MJML 4 stripping behavior.

Outlook Stability

• Automatic VML for background images (section and hero only — the only locations where Outlook generates VML)
• Font fallback protection via <mj-font>, which wraps @font-face imports in MSO conditional comments so Outlook ignores them and uses the system fallback stack instead of Times New Roman
• Background positioning restricted to keyword values (top, center, bottom) — pixel values are silently ignored by Outlook

Zero-Stacking Guarantee

Multi-column layouts that must stay side-by-side on mobile (social bars, logo rows, icon grids) use <mj-group> to prevent stacking. The whitespace-triggered stacking bug is neutralised by the font-size:0px MJML sets on the containing cell, which renders any inter-tag whitespace zero-width across iOS Mail and Android Gmail.

Head-First Optimization