Will My Email Look Right? A Client Compatibility Guide

You built a beautiful email. It looks perfect in your browser. You send a test to yourself and it renders correctly in Apple Mail. You feel confident.

Then your colleague opens it in Outlook and asks why the layout is broken.

This is the central frustration of email development. Unlike the web, where browsers have largely converged on standards, email clients are still a fragmented landscape of rendering engines, each with their own interpretation of what HTML and CSS should do.

This guide covers the three clients that matter most and the specific issues you'll encounter in each.

The big three

Gmail

Market share: ~30% of all email opens, depending on your audience.

Rendering engine: Blink (Chromium-based), but heavily sandboxed.

The good: Gmail renders modern HTML reasonably well. Colors, fonts, images, and basic layout all work. It supports a decent subset of CSS.

The bad:

• Strips <style> blocks in many contexts. Gmail originally removed all <style> tags; it now supports them in some cases, but the behavior is inconsistent across Gmail web, Gmail Android, and Gmail iOS.
• Removes classes it doesn't recognize. If your class name starts with a number or contains certain characters, it's gone.
• No CSS custom properties. var(--brand-color) becomes nothing.
• No calc(). Dynamic sizing won't work.
• No background-image on <div> elements. Background images work on <td> but not reliably on other elements.
• Aggressive style inlining. Gmail rewrites your HTML and adds its own classes, which can conflict with your styles.

Practical impact: Design for inline styles. Don't rely on <style> blocks being present. Use table-based layout. MJML handles all of this for you.

Outlook (Windows)

Market share: ~8-10% overall, but 30-50% in corporate/B2B contexts.

Rendering engine: Microsoft Word's HTML renderer. Yes, really.

The good: It's consistent — it renders the same way every time. Just... not the way you'd expect.

The bad:

• No border-radius. Rounded corners don't exist in Word's renderer. Your beautiful rounded buttons become rectangles.
• No background-image on most elements. You need VML (Vector Markup Language) — a Microsoft-specific XML format — to get background images working.
• max-width is ignored. If you're using max-width for responsive containers, Outlook will blow right past it.
• padding behaves unpredictably on <td> elements. Sometimes it works. Sometimes it doesn't. The workarround is often nested tables with explicit widths.
• Line-height is unreliable. Outlook adds extra space to text elements. The fix: mso-line-height-rule: exactly.
• Animated GIFs show only the first frame. Your carefully crafted animation becomes a static image.

Practical impact: If your audience includes corporate users, test in Outlook. MJML generates the necessary VML and mso- prefixed styles automatically, which handles most of these issues. But you should still verify the output.

Apple Mail (macOS & iOS)

Market share: ~35-40% of all email opens (iOS Mail is the single largest email client by opens).

Rendering engine: WebKit, the same engine as Safari.

The good: Almost everything works. CSS Grid? Sure. Flexbox? Yes. Animations? Go for it. Web fonts? Supported. It's the closest thing to a real browser that exists in the email world.

The bad:

• Dark mode rewrites your colors. (More on this below.)
• It's too forgiving. If your email only looks good in Apple Mail, you haven't tested enough. The fact that Apple Mail renders everything doesn't mean other clients will.

Practical impact: Apple Mail is not a reliable test target by itself. Always also test in Gmail and Outlook.

Dark mode and how it ruins your colors

Dark mode support in email is a mess. Here's why:

Apple Mail inverts light backgrounds to dark and dark text to light — automatically, without asking. It does a reasonable job, but it will change your brand colors.

Gmail (Android dark mode) is less aggressive but still modifies colors in unpredictable ways.

Outlook (Windows) mostly ignores dark mode in email rendering. Dark mode applies to the Outlook UI but generally leaves email content alone.

What you can do about it

1. Use @media (prefers-color-scheme: dark) styles. Apple Mail and a few other clients respect this. You can specify explicit dark-mode colors for backgrounds, text, and borders.

2. Add a thin border to images with transparent backgrounds. In dark mode, a logo with a transparent background can become invisible if both the logo and the new background are dark.

3. Avoid pure white (#ffffff) backgrounds. Use #fafafa or #f8fafc — dark mode algorithms are less aggressive with off-whites.

4. Test with dark mode on. This sounds obvious but most people don't do it until a recipient complains.

5. Accept imperfection. You cannot fully control dark mode rendering across all clients. Make sure nothing breaks (invisible text, unreadable buttons) and accept that colors will shift.

Images: when they load, when they don't

Image blocking

Many email clients — particularly Outlook — block images by default until the user clicks "Download images." This means:

• Your hero image might not show. The user sees a blank space or a broken icon.
• Background images are invisible. You need a solid fallback color.
• Image-only emails are effectively blank for a significant portion of your audience.

What to do

• Always set alt text. When images are blocked, the alt text displays instead. Make it descriptive: "Product photo: red sneakers on white background" is more useful than "image1."
• Set width and height attributes. This preserves layout structure even when images are blocked.
• Don't put critical information only in images. Your main headline, CTA text, and key message should be in HTML text, not baked into a graphic.
• Use a background color behind images. So the area isn't just blank white if the image doesn't load.

Image formats

• JPEG for photos. Compress to a reasonable file size — 50-100KB for a hero image is fine.
• PNG for graphics, logos, and anything with transparency.
• GIF for simple animations — but remember Outlook shows only the first frame.
• SVG is not reliably supported. Avoid it in emails.
• WebP has growing support but isn't universal yet. Stick with JPEG/PNG for maximum compatibility.

Image sizing

• Max width: 600px for the email container. Design images at 2x (1200px wide) for retina displays, but set the display width to 600px or less.
• Keep total email weight under 100KB (excluding images) for fast loading and to avoid Gmail's clipping threshold.
• Gmail clips emails over ~102KB. If your HTML exceeds this, Gmail shows a "View entire message" link and hides the rest. Your footer, unsubscribe link, and final CTA might be invisible.

Mobile rendering: why 60%+ of opens are on phones

More than half of all email opens happen on mobile devices. In many B2C segments, it's closer to 70%. This has specific design implications:

What changes on mobile

• Single-column layout is king. Multi-column layouts stack vertically on small screens. If your two-column layout doesn't make sense when stacked, rethink it.
• Tap targets need to be large. Apple's Human Interface Guidelines recommend 44x44px minimum. Your buttons should be at least this big — ideally bigger.
• Font size matters more. Body text at 14px is barely readable on a phone. Use 16px minimum.
• Preview text is crucial. On mobile, the preview text (the gray text after the subject line in the inbox) often determines whether someone opens your email. Set it intentionally.

Responsive vs. fluid

• Responsive emails use media queries to change layout at breakpoints (typically 480px). Columns collapse, images resize, font sizes adjust.
• Fluid emails use percentage-based widths that adapt continuously. Simpler to implement, fewer potential breakpoints to debug.

MJML generates responsive HTML by default. Columns stack on mobile. Images scale down. Padding adjusts. You don't have to write media queries manually.

What MJML handles automatically

If you're using ModuLetter (which compiles through MJML), here's what you don't need to worry about:

• Table-based layout generation — handled
• Inline style injection — handled
• Outlook conditional comments and VML — handled
• Responsive column stacking — handled
• mso- prefixed style fixes — handled
• Font fallback stacks — handled
• Gmail <style> stripping workarounds — handled

What you do still need to watch for:

• Dark mode color shifts — test manually
• Image blocking behavior — always set alt text and fallback colors
• Gmail 102KB clipping — keep your emails focused and concise
• Content choices — no tool can fix bad copy or an unclear CTA

ModuLetter gives you the infrastructure. The content decisions are still yours.

Open ModuLetter and build something →