| name | 49-html-email-template-global |
| description | Use when responsive HTML email has to render correctly in every client — table-based structure, inline CSS, 600px max width, dark mode handling, quirks for Gmail, Apple Mail, Outlook and Yahoo, bulletproof buttons, and a pre-send test checklist, shipping a self-contained .html file to paste into Klaviyo, Mailchimp, HubSpot, or Brevo. Trigger on 'HTML email', 'code an email template', 'responsive email', 'why does my email break in Outlook', 'email dark mode is broken', 'the newsletter looks wrong on mobile'. Not for — sequence strategy and subject lines, see `14-email-marketing-global`; a web page, see `12-landing-page-brief-global`; brand colors and fonts, see `46-brand-guideline-global`. |
| metadata | {"version":"1.0.1","category":"operations"} |
| license | MIT |
| triggers | ["HTML email","code an email","email template","responsive email","email broadcast HTML","why does my email break in Outlook","email dark mode"] |
| output | A single self-contained .html file — paste it into the ESP (Klaviyo, Mailchimp, HubSpot, Brevo) and send. Ships with a client test checklist. |
| related | ["product-marketing-context-global","14-email-marketing-global","46-brand-guideline-global","47-design-review-global","12-landing-page-brief-global"] |
HTML Email Template (Global)
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
img needs 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) |
