HTML email development best practices

The NSW Email Framework, built on Maizzle and the NSW Design System tokens, provides tools and components to create accessible, responsive HTML emails. However, coding emails remains very different from coding web pages due to inconsistent support across email clients.

This guide outlines best practices across five areas:

• CSS resets
• Inlining CSS
• Email client support
• Outlook conditional CSS
• Testing across platforms

These practices help ensure your emails display consistently and remain accessible.

Apply CSS resets and use safe layout widths

Reset default styles

Email clients, like web browsers, apply default CSS that may conflict with your styles. For example, some webmail clients set line-height or margins by default.

The NSW Email Toolkit framework includes the community-maintained email-normalize module from Maizzle. It resets or neutralises:

• default margins (e.g. no default body margin)
• inconsistent line heights (e.g. Outlook.com's 142% default on text)

This creates a clean foundation for consistent rendering.

Use a fixed width layout

Design your emails using a fixed width of 600–640 pixels. Although 600 pixels was once the standard, modern guidance supports up to 640 pixels without causing rendering issues or horizontal scroll. This size:

• aligns with legacy and modern clients
• ensures optimal readability on mobile and desktop
• prevents background colour cut-offs in some Gmail clients

Optimise and host images properly

To maintain performance and visual consistency:

• Compress images to reduce file size and improve load times.
• Use HTTPS to avoid blocked content or mixed-content warnings.
• Set width and height attributes on <img>tags to prevent layout shifts and improve accessibility.

Inline CSS for reliable rendering

Most email clients either strip or ignore <style> tags. Inlined CSS is the most reliable way to ensure consistent styling.

Why inline styles?

• Gmail removes <head> styles.
• Outlook for Windows uses Microsoft Word to render HTML, with limited CSS support.
• Forwarded emails or mobile apps may drop embedded styles.

Framework automation

The NSW Email Framework automates CSS inlining at build time using Juice. You can:

• write HTML with Tailwind utility classes
• output HTML with all styles inlined
• avoid issues like Outlook ignoring multiple class names

Inline styles also improve testing, as the final HTML reflects exactly what users receive.

Benefits

• Less boilerplate: Focus on content; the framework handles compatibility.
• Reliable rendering: Styles are fully expanded and client-specific issues are addressed.
• Streamlined QA: Easily validate and test the compiled HTML.
• Flexible configuration: Adjust or disable inlining via config.js. Use data-embed to exclude specific rules if needed.

Understand email client differences

HTML emails render differently across clients. There is no universal standard, so your code must degrade gracefully.

Outlook (Windows desktop)

• Uses Microsoft Word as its rendering engine.
• Requires table-based layouts and inline CSS.
• Lacks support for flexbox, grid and some CSS shorthands.

Fallbacks are essential – such as nested tables for layout and VML for visual elements.

Gmail and modern clients

• Supports most CSS properties, media queries and embedded styles.
• Gmail's web client uses Blink (Chrome) with sandboxing.
• The framework supports Tailwind classes and inline fallbacks to maintain consistency.

Other clients

Clients such as Yahoo, Samsung Mail, ProtonMail and Thunderbird vary in support. The framework uses conservative defaults and references “Can I Email” support tables to guide compatibility decisions.

Where support is partial, the framework includes accessible fallbacks to ensure content remains readable.

Use conditional CSS for Outlook

To manage Outlook-specific issues, use conditional comments (MSO conditionals) that only Outlook will interpret.

<!--[if mso]>
  ... Outlook-only HTML/CSS here ...
<![endif]-->

Use cases

• Fallback tables: Use tables within MSO conditionals to preserve layout where modern techniques fail.
• VML graphics: Add rounded buttons or background images using VML within conditional blocks.
• Style overrides: Apply specific fixes, such as line-height rules, using conditional <style> blocks.

Outlook conditionals are preserved by the build process in the framework. Just avoid stripping comments during minification.

Test your emails thoroughly

Testing is essential due to variation in rendering engines and user settings (such as dark mode).

Test across major clients

At a minimum, test your templates in:

• Outlook (desktop)
• Gmail (web and mobile)
• Apple Mail (macOS and iOS)
• Outlook.com
• Yahoo Mail

Use tools like Litmus or Email on Acid for full previews across platforms.

Consider dark mode and accessibility

Dark mode may automatically invert colours, affecting contrast or readability. To ensure accessibility:

• Use dark-mode-friendly colour tokens.
• Test contrast in light and dark modes.
• Avoid colour-only distinctions.
• Use semantic HTML and alt text for images.

Final guidance

Never assume an email will render consistently everywhere. Rely on robust testing, fallback structures and inlined CSS to deliver accessible, professional emails.

By using these best practices, your emails will be more resilient, inclusive and consistent across all platforms.

Sources