Email HTML is not web HTML: it needs table layout, inline CSS, and avoidance of everything clients do not support. The bar is simple — it looks right in Gmail, Apple Mail, Outlook, and Yahoo, and it reads on a 375px phone. No exceptions. Content and sequence come from 14-email-marketing-global; this skill handles the code.
Information gathering
Read the brand guideline (46-brand-guideline-global) and the email content from 14-email-marketing-global if available. If information is missing, ask up to 4 questions:
- Email type and layout? Welcome, broadcast, nurture, offer, or transactional — single column, two columns with a product image, or a multi-section newsletter?
- Which sections? Header, hero, body, social proof, CTA, footer — is there a hero image?
- Is the copy written? Or should the template ship with placeholders? Where does the primary CTA link?
- Which ESP sends it? Klaviyo, Mailchimp, HubSpot, Brevo, Braze, or other — merge tag syntax differs per platform.
Principles
- Table layout only — no div/flexbox/grid/float/position:absolute. Outlook on Windows renders through the Word engine and does not support them.
- Inline all CSS. Gmail can strip
<style>blocks; keep only media queries and dark-mode rules in<style>, and inline everything else. - 600px maximum width, degrading to 375px.
- System-font fallbacks: '[body font]', Arial, Helvetica, sans-serif. Never depend on a web font — many clients will not load it.
- Every
imgneeds alt text plus width and height attributes so a blocked-image inbox still reads correctly. - Unsubscribe link and a physical postal address are legally required (CAN-SPAM in the US, GDPR and PECR in the EU/UK, CASL in Canada). Honor opt-outs promptly.
- Test on mobile first. The majority of opens are on a phone.
- One self-contained .html file, under 100KB — Gmail clips messages past roughly 102KB.
Workflow
1. Choose the layout
| Layout | Use for |
|---|---|
| Single column | Broadcast, nurture — most readable, fewest rendering bugs |
| Two column (image + text) | Offer emails with a product image |
| Multi-section newsletter | Digest, updates — one table block per section |
2. Build to the technical spec
Container: 600px desktop / 100% mobile
Outer background: light neutral (e.g. #F4F4F4)
Body background: [background color] (usually white)
Font: '[body font]', Arial, Helvetica, sans-serif
Body font-size: 16px / line-height: 1.6
Mobile breakpoint: max-width 480px
Design tokens come from the brand guideline:
- Header: ground [primary color], reversed logo, padding 20px.
- Hero: ground [primary color] or a gradient from [primary color] to [secondary color]; headline bold 28px in a light fill; subtext 16px; CTA button.
- Body: light ground, padding 40x48px desktop / 24x20px mobile; H2 bold 22px in [strong text color]; body 16px, line-height 1.7.
- CTA button: ground [primary color], bold 16px light text, padding 14x32px, radius 8px,
display:inline-block, no underline. Outlook Windows will not drawborder-radius— accept the square fallback, and never use an image as the button. - Social proof: quote on [light background color], 4px left border in [primary color], attributed name and role.
- Footer: light neutral ground, 13px [muted text color] — small logo around 80px, website and social links, postal address, unsubscribe, copyright.
3. Fill the sections
- Header: logo, centered.
- Hero: optional preheader text, headline (max 60 characters), subtext (max 100 characters), CTA button, optional hero image 600x300 with alt text.
- Body: greeting with a merge tag, 2-3 opening sentences, main content in short paragraphs (max four sentences), bulleted content built as table rows rather than
ulfor safer rendering, optional secondary CTA. - Footer (mandatory): company postal address, unsubscribe line ("You are receiving this because you signed up at [website] | Unsubscribe"), copyright.
4. Handle mobile and dark mode
@media only screen and (max-width: 480px) {
/* container: 100% width */
/* body font: 15px */
/* CTA: full width, centered */
/* padding: 24px 20px */
/* images: 100% width */
}
Dark mode:
- Add
<meta name="color-scheme" content="light dark">and<meta name="supported-color-schemes" content="light dark">. @media (prefers-color-scheme: dark)is only partially supported: Apple Mail honors it well; Gmail typically applies its own color inversion and ignores the media query; Outlook may force a full invert.- Safe rules when dark mode cannot be controlled: use a transparent-background PNG logo that reads on both light and dark grounds (or add a light stroke); never use pure black text on a transparent ground; give important blocks such as the CTA a solid background color; test in at least one dark-mode client before sending.
5. Fill the required placeholders
- First-name merge tag — syntax depends on the ESP
- Unsubscribe link — legally required
- Company postal address — must be real
- Primary CTA link — real URL with UTM parameters per
14-email-marketing-global
| ESP | First-name merge tag | Unsubscribe |
|---|---|---|
| Klaviyo | {{ first_name|default:"there" }} |
{% unsubscribe %} |
| Mailchimp | *|FNAME|* |
*|UNSUB|* |
| HubSpot | {{ contact.firstname }} |
injected automatically |
| Brevo | {{ contact.FIRSTNAME }} |
{{ unsubscribe }} |
Always confirm the exact syntax in the sending platform before the final send — an unrendered merge tag in a live send is a visible error.
Email client matrix
| Client | Rendering behavior | What to do about it |
|---|---|---|
| Gmail (web and app) | May strip <style> in some contexts; applies its own dark-mode inversion |
Inline everything; the single-column layout must read even if media queries are dropped |
| Apple Mail (macOS/iOS) | WebKit — the most capable renderer | Supports media queries and prefers-color-scheme properly; use it as the dark-mode reference |
| Outlook desktop (Windows) | Word rendering engine | Tables only; no border-radius, unreliable background images (use solid colors); test separately |
| Outlook.com / new Outlook | Chromium-based, much better than desktop | Still avoid flex and grid for consistency with desktop |
| Outlook mobile (iOS/Android) | Reasonable modern rendering | Verify CTA tap targets at 44px minimum height |
| Yahoo Mail / AOL | Decent support, varies by build | Send a real test to a live account |
| Mobile in general | 375px screens | Body font 15px or larger, CTA at least 44px tall for thumbs |
Measurement note
Apple Mail Privacy Protection pre-fetches tracking pixels, which inflates reported open rates for any list with a meaningful Apple Mail share — and Gmail image proxying adds noise of its own. Treat open rate as a directional signal only. Judge template and campaign performance on click-through rate, click-to-open rate, and conversions. Global email medians for context: open 22-27%, CTR 2.5-3.5%, CTOR 10-14%, unsubscribe below 0.5%.
Pre-send test checklist
- Gmail desktop and Gmail mobile app
- Apple Mail on iPhone
- Outlook desktop on Windows (if the list skews corporate)
- Yahoo or another webmail account
- Dark-mode preview in at least one client
- Every link works — especially the CTA and the unsubscribe
- Alt text on every image; the email still makes sense with images blocked
- HTML file under 100KB (avoids Gmail clipping)
- Merge tags use the sending platform's syntax and render correctly
- Real seed send to 2-3 different inboxes before the list send
- Subject line and preheader filled in (from
14-email-marketing-global) - Postal address and unsubscribe present and accurate
Related skills
14-email-marketing-global: strategy, sequence, content, and subject lines — written before the code.46-brand-guideline-global: colors, fonts, and logo for the email design tokens.47-design-review-global: review the email before sending (brand, readability, CTA, platform fit).12-landing-page-brief-global: the CTA usually lands on a landing page — keep the message consistent across both.
Quality checklist
- Table layout, no flexbox, grid, float, or absolute positioning
- All CSS inline except media queries and dark-mode rules
- 600px width, degrading to 375px without breaking
- System font fallbacks, no dependency on web fonts
- CTA button is solid, at least 44px tall on mobile, not an image
- Footer carries postal address, unsubscribe, and copyright
- Dark-mode meta tags added and the safe rules applied
- Full test checklist executed before sending
- One self-contained .html file, under 100KB