Getting Started
Building an HTML email is not building a web page. The constraints are different, the toolchain is different, and the techniques are different. Internalize that before writing a line of code, and the rest of this playbook will make sense.
The mental model
Section titled “The mental model”Treat an email like a document from 2005 that has to render in every mail client made since. Specifically:
- Layout is tables. Always. Nested tables for everything structural.
- CSS is inline. Style attributes on every element. Stylesheets in
<head>are unreliable. - JavaScript does not exist. Most clients strip it; some flag the email as malicious.
- External resources are risky. Web fonts may not load. External CSS will be stripped. Images may be blocked by default.
- Outlook is the floor. If it renders in Outlook 2016 on Windows, you’re safe.
What you’re optimizing for
Section titled “What you’re optimizing for”- Cross-client rendering. The same code must look acceptable in 10+ rendering engines.
- Accessibility. Screen readers need semantic structure.
role="presentation"on layout tables. - Inbox delivery. Heavy or malformed emails get flagged. Stay lean.
- Mobile usability. Half of opens are on phones. Tap targets, font sizes, single-column collapse.
What you’re NOT optimizing for
Section titled “What you’re NOT optimizing for”- Pixel-perfect parity across clients. Impossible. Aim for “looks good and works” everywhere.
- Modern CSS features. No CSS Grid, no Flexbox (in production), no custom properties for layout.
- Animations or interactivity. Some clients support limited CSS animation, but never rely on it.
The toolchain (minimal)
Section titled “The toolchain (minimal)”You don’t need a build pipeline. You need:
- A code editor.
- A browser (for the first visual check).
- A real email client testing service: Litmus, Email on Acid, or Mailtrap for previews.
- Real test inboxes: one Gmail account, one Outlook.com account, one Apple Mail / iCloud account, one Yahoo.
How this playbook is structured
Section titled “How this playbook is structured”The pages are ordered the way I’d build a template from scratch:
- Head structure — the boilerplate that makes everything else work.
- Body container — the outermost table and the
<body>setup. - Header / Body / Footer — the three logical sections of the email, each its own nested table.
- Components — spacing, images, buttons, text. Reused everywhere.
- Compatibility — Outlook quirks, RTL, responsive.
- Production — Gmail clipping, dark mode, preheader, bulletproof buttons.
Go to Head Structure →