Structure
The bones of every email: doctype, head boilerplate, the body container, and the header / body / footer table architecture.
HTML Email Playbook
Email development is its own universe. The CSS rules you trust break, the HTML you stopped using a decade ago becomes essential again, and Microsoft Outlook on Windows quietly determines half of your decisions.
This playbook is the working reference I keep open while building templates. It covers the boilerplate, the table architecture, the Outlook compatibility hacks, and the production checks that catch problems before send.
When to use this
Section titled “When to use this”You’re hand-building HTML emails (not using MJML, Foundation for Emails, or a builder). You need them to render in:
- Microsoft Outlook (Windows desktop)
- Outlook 365 / Outlook.com
- Gmail (web + mobile apps)
- Apple Mail (macOS + iOS)
- Yahoo Mail
- Mobile native clients
If you’re using a generator like MJML, most of these problems are solved for you. If you’re hand-coding for control or constraints, you’re in the right place.
How it’s organized
Section titled “How it’s organized”Components
Reusable building blocks: spacing patterns, images, background images (VML), buttons, and text. Each one inline-styled and cross-client tested.
Compatibility
The places email engines diverge: Outlook MSO conditional comments, RTL support, and responsive behavior on mobile clients.
Production
What separates an email that renders from an email that performs: Gmail’s 102KB clip, dark mode, preheader text, and bulletproof buttons.
Conventions in this guide
Section titled “Conventions in this guide”Start here
Section titled “Start here”If this is your first time, read Getting Started for the mental model. If you already know the landscape, jump to the head structure.