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 Design System 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.
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
- Good Email Code. (n.d.). Good Email Code. (accessed on 1 September 2025).
- Github. (n.d.). email-normalize. (accessed on 1 September 2025).
- Mailchimp. (n.d.). HTML Email Basics. (accessed on 1 September 2025).
- Email on Acid. (n.d.). HTML Email Development Best Practices: Rules to Code By. (accessed on 1 September 2025).
- Litmus. (n.d.). Foundations of Email Development. (accessed on 1 September 2025).
- Maizzle. (n.d.). Maizzle. (accessed on 1 September 2025).
- Can I email. (n.d.). Can I email. (accessed on 1 September 2025).
- Litmus. (n.d.). Outlook Email Rendering Issues and How to Solve Them. (accessed on 1 September 2025).
- mailtrap. (n.d.). Email Client Testing Explained. (accessed on 1 September 2025).
- Email on Acid. (n.d.). Conditional CSS for Email: What Developers Need to Know. (accessed on 1 September 2025).
- Google for Developers Workspace. (n.d.). CSS Support. (accessed on 1 September 2025).
- Litmus. (n.d.). The State of Email Client Market Share. (accessed on 1 September 2025).
- Stack Overflow Design. (n.d.). Outlook conditional CSS. (accessed on 1 September 2025).
- inagiffy. (n.d.). A Guide to Outlook Email Rendering Issues. (accessed on 1 September 2025).