If you have ever built a website, forget most of what you know when coding HTML emails. Email clients use different rendering engines, strip CSS properties, and interpret HTML in unexpected ways. What works in a browser often breaks spectacularly in Outlook.
This guide covers the techniques and workarounds needed to code HTML emails that work reliably across all major email clients.
Email Client Rendering
The Rendering Landscape
Email clients do not share a common rendering engine. Apple Mail uses WebKit with good modern CSS support. Gmail uses its own rendering that strips most CSS. Outlook on Windows uses Microsoft Word's rendering engine with severe limitations. Each webmail client has its own quirks.
The Lowest Common Denominator
To achieve consistent rendering, code for the most limited clients, primarily Outlook on Windows. If it works in Outlook, it usually works everywhere. If it only works in Apple Mail, it will break for millions of users.
Email HTML Structure
DOCTYPE and HTML Setup
Use the XHTML 1.0 Transitional DOCTYPE for the best compatibility across clients. Include proper xml namespace declarations and set the Content-Type meta tag with UTF-8 charset.
Table-Based Layout
Tables are the only reliable layout mechanism in email. Do not use div-based layouts for email - they break in Outlook and other clients. Use nested tables for complex layouts, role="presentation" for accessibility, explicit cellpadding, cellspacing, and border of zero, and explicit widths on table cells.
Wrapper Table Pattern
Start with a full-width wrapper table that centers your content. Inside that, place your actual content table with a fixed width, typically 600 pixels for desktop compatibility.
CSS in Email
Inline Styles
Gmail strips style blocks from the head. Every element that needs styling must have inline styles. Write normal CSS during development, then use a CSS inliner tool for production.
Supported CSS Properties
These properties work reliably: background-color, border, color, font-family, font-size, font-weight, line-height, padding, text-align, text-decoration, and width. Use these as your primary styling tools.
Problematic CSS Properties
These properties have limited or no support: margin (use padding instead), float (use tables), position (not supported), display flex or grid (not supported), max-width (partial support), and most pseudo-selectors. Avoid relying on these properties.
Fallback Patterns
Use both bgcolor and background-color for backgrounds. Use both width attributes and CSS width. Always provide fallback fonts. Test every property in actual email clients.
Responsive Email Techniques
Fluid Hybrid Method
This approach works without media queries by using table cells that stack naturally on small screens. Set width to 100% with max-width of 300px on desktop columns. Outlook ignores max-width, so use conditional comments to set fixed widths for Outlook.
Media Query Responsive
For clients that support media queries, add them in a style block. Use breakpoints around 600px for mobile. Override widths, font sizes, and visibility. Remember that Gmail does not support media queries in many contexts.
Outlook Conditional Comments
Use conditional comments to serve different code to Outlook. The syntax using mso if statements lets you include Outlook-specific fixes that other clients ignore.
Images in Email
Image Best Practices
Always include alt text, set explicit width and height attributes, use display block to prevent gaps, host images externally on HTTPS URLs, optimize file sizes, and provide fallback background colors.
Retina Images
For crisp display on high-DPI screens, provide images at 2x resolution but constrain display size with width and height attributes or CSS width.
Background Images
Background images have limited support. Outlook does not support CSS background-image on most elements. Use VML (Vector Markup Language) for Outlook background images. Always provide a solid background-color fallback.
Typography in Email
Web Fonts
Web fonts have very limited email support. Google Fonts work in some clients like Apple Mail and iOS Mail. They do not work in Gmail, Outlook, or Yahoo. Always provide system font fallbacks. Design to look good with fallbacks.
System Font Stack
A good fallback stack includes Apple system font, BlinkMacSystemFont, Segoe UI, Roboto, Helvetica, Arial, and sans-serif. This provides native-looking fonts on all platforms.
Typography Styling
Use explicit font-size in pixels (not em or rem), set line-height as a number or pixels, use font-weight with numeric values when possible, and apply text styling to every text element.
Buttons in Email
Bulletproof Buttons
Do not use images for buttons - they may not load. Do not use just anchor tags - they are hard to style consistently. Use table-based buttons with proper padding for click area, background color on the table cell, and styled anchor tag inside. This pattern works across all clients.
Button Best Practices
Make buttons at least 44px tall for mobile tap targets. Use high contrast colors. Include clear action text. Use border-radius for rounded corners where supported with square fallback.
Testing and Debugging
Testing Tools
Litmus and Email on Acid provide previews across dozens of email clients. Always test before sending. Test responsive behavior, dark mode, and images-off state.
Common Issues and Fixes
Unwanted spacing often comes from whitespace in HTML - remove line breaks between table cells. Blue links on iOS happen because iOS auto-links dates and addresses - wrap in span with explicit color. Images not displaying could be blocked images - always provide alt text and background colors.
Debugging Process
- Identify which clients have the problem
- Isolate the problematic section
- Check CSS property support for those clients
- Test fixes in isolation
- Verify fixes do not break other clients
Dark Mode
Dark Mode Behavior
Email clients handle dark mode differently. Some invert colors automatically, some respect color-scheme meta tags, and some do nothing. Test your emails in dark mode.
Dark Mode Strategies
Use transparent PNGs for logos when possible. Avoid pure white backgrounds. Add dark mode styles using prefers-color-scheme media query where supported. Accept that you cannot control dark mode perfectly everywhere.
Conclusion
HTML email coding requires embracing constraints rather than fighting them. Tables for layout, inline styles, defensive coding, and extensive testing are necessary for reliable rendering.
The good news is that once you learn the patterns, email coding becomes predictable. The same techniques work across projects.
GetMailer provides tested email templates built with these best practices. Our templates render correctly across all major clients, so you can focus on your content rather than fighting email client quirks.