Email HTML compatibility
Email clients are not browsers. Each one runs its own renderer, and between them they remove tags, drop stylesheets, and ignore properties that work everywhere else on the web. The compatibility checker reads a template's HTML and reports the patterns that will not survive.
A problem means the pattern does nothing at all. The client removes the markup, never loads the stylesheet carrying it, or will not operate the control. Where a finding names clients, that is what happens in those clients. A warning means it does something, but not what you wrote.
Every finding names the pattern and the line it sits on. It names the clients affected where only some of them are, and what to use instead where there is a drop-in alternative. None of them refuses a save, a publish, or a send: a feature most clients lack is still the right choice for an audience whose client supports it.
What the checker reports
| Rule | Severity | What it means |
|---|---|---|
html_script | problem | Email clients remove <script> tags. |
html_event_handlers | problem | Email clients strip JavaScript event handlers like onclick. |
html_embedded_content | problem | Email clients remove <iframe>, <embed>, and <object> content. |
html_linked_stylesheet | problem | Linked stylesheets are ignored in Gmail, Outlook (macOS/Outlook.com/iOS/Android), and Yahoo, so those styles won't load. |
css_at_import | problem | @import stylesheets are ignored in Gmail, Outlook (macOS/Outlook.com/iOS/Android), and Yahoo. |
html_form | problem | Forms don't work reliably in email. Link to a hosted form instead. |
html_svg | problem | Inline <svg> doesn't render in Gmail, Outlook, and Yahoo. Use an <img> instead. Partial support for inline <svg> in Apple Mail (macOS). |
html_media | warning | <video> and <audio> don't play in Gmail, Outlook, and Yahoo. Partial support for <video> and <audio> in Apple Mail (iOS). |
css_display_flex_grid | warning | display: flex and grid don't work in Outlook (Windows/Windows Mail). Use tables for layout. Partial support for display: flex and grid in Gmail (iOS/Android). |
css_position_fixed_sticky | warning | position: fixed and sticky are ignored in Gmail and Outlook (Windows/Windows Mail/iOS). Partial support for position: fixed and sticky in Apple Mail, Outlook (macOS/Outlook.com/Android), and Yahoo. |
css_variables_no_fallback | warning | CSS variables get stripped in Gmail, Outlook, and Yahoo. Add a fallback like var(--brand, #000). |
css_viewport_units | warning | Viewport units like vh and vw aren't supported in Outlook (Windows/Windows Mail). Partial support for viewport units like vh and vw in Apple Mail (iOS). |
html_button | warning | <button> renders unreliably in Outlook (Windows/Windows Mail/macOS/Outlook.com/iOS) and Yahoo. Use a styled link instead. Partial support for the <button> tag in Gmail (iOS). |
css_math_functions | warning | clamp(), min(), and max() don't work in Outlook and Yahoo. Partial support for clamp(), min(), and max() in Gmail (iOS/Android). |
css_modern_color | warning | Color functions like oklch() don't work in Gmail, Outlook, and Yahoo. |
html_web_page_markup | warning | A web framework left this markup behind. It is harmless, and an email has no use for it. |
A finding names the line to change. Previewing a template reports them for the content you supply, in the builder as you edit and from bird email templates preview on the command line. To see what a template actually looks like in a client, send it to yourself with Test email from the template or broadcast header.
Related
- Preview an email template: the command that returns a report for content you supply
- Template and content issues: how content affects whether the mail arrives at all