Email Rendering Bugs: The Developer's Field Guide to Why Emails Break

Symptom: A 600px centered newsletter expands to the entire width of a 34-inch ultrawide monitor, or two 300px columns refuse to sit side-by-side and stack awkwardly.

Root Cause: Word has no concept of CSS max-width, min-width, or display: flex. It treats divs as unconstrained block containers.

The Fix: Wrap the responsive container in an MSO ghost table (<!--[if mso]><table width="600">...<![endif]-->). This enforces rigid physical boundaries in Word while allowing modern mobile clients to scale fluidly.

Symptom: Hero banners render with missing photography, leaving white text on an empty background.

Root Cause: Word strips both CSS background-image and HTML background="..." attributes.

The Fix: Implement Vector Markup Language (VML) <v:rect> and <v:fill> containers. Word interprets VML as native vector graphics, projecting the bitmap behind overlay typography.

Symptom: Thin, white or transparent horizontal lines slice through sliced hero images or table cells on Surface tablets and high-resolution laptops.

Root Cause: When Windows runs at 125% (120 DPI) or 150% (144 DPI) display scaling, Word recalculates table borders and cell widths with fractional sub-pixels, causing rounding errors that reveal background gaps.

The Fix: Declare <o:PixelsPerInch>96</o:PixelsPerInch> in the <head>, enforce border-collapse: collapse; and ensure table cells do not use odd-numbered fractional heights.

Symptom: A hero background vanishes, and CTA buttons further down the email render as blank colored rectangles without text.

Root Cause: Placing a VML rounded button (<v:roundrect>) inside a VML background (<v:rect>) corrupts Word's rendering tree. Outlook drops the container fill completely and suppresses text drawing for all subsequent VML shapes across the document.

The Fix: Never nest VML shapes. Use table-cell buttons with CSS border-radius inside hero banners instead of VML shapes.

Symptom: Stacking utility classes (e.g. class="btn primary") causes secondary styles to be silently ignored in desktop Outlook.

Root Cause: Classic Outlook's Word parser evaluates only the first class name on an element when styles conflict. Properties defined on subsequent classes are discarded.

The Fix: Avoid chaining utility classes on the same element. Merge conflicting declarations into a single class (e.g. .btn-primary) or inline the critical declarations.

Symptom: The entire second half of your email loses styling exclusively in Outlook.com and Outlook iOS/Android.

Root Cause: Minified CSS ending with two adjacent closing curly braces (}}), such as a rule closing inside a media query, breaks Outlook.com's CSS preprocessor. It discards every single style rule following the double brace.

The Fix: Ensure your minifier preserves a space or newline between adjacent closing braces (} }).

Symptom: Footers vanish, legal disclaimers and unsubscribe links disappear, and email open rates drop sharply.

Root Cause: If the raw HTML payload exceeds 102KB (104,448 bytes), Gmail cuts off the email and inserts “[Message clipped] View entire message.” Because tracking pixels sit at the bottom of the body HTML, clipping destroys deliverability telemetry.

The Fix: Strip redundant inline CSS, eliminate inline base64 images, and test HTML payload size with our Gmail clipping guide and Email Size Checker.

Symptom: Media queries, mobile responsiveness, or custom classes defined later in your stylesheet fail to render in Gmail, even though the email is well under the 102KB clipping limit.

Root Cause: Gmail calculates the cumulative byte size of all <style> blocks. Once total CSS exceeds 16 KB (16,384 bytes), Gmail silently discards all remaining CSS declarations across the document without raising an error.

The Fix: Keep embedded head styles strictly under 16KB. Purge unused utility classes, eliminate verbose CSS comments, and inline core structural layouts.

Symptom: An entire <style> tag vanishes, or an element loses all inline styles including padding, borders, and typography.

Root Cause: Modern CSS allows space-separated color arguments (e.g. rgb(30 41 59) or hsl(210 50% 20%)). When Gmail's parser encounters a space-separated color in a <style> block, it deletes the entire block. When used in an inline style attribute, Gmail drops every single declaration on that element, not just the color.

The Fix: Always use traditional comma-separated syntax: rgb(30, 41, 59) and rgba(30, 41, 59, 0.8).

Symptom: The entire email loses all custom styling in Gmail, reverting to browser-default serif typography and unstyled tables.

Root Cause: Gmail parses the <style> tag in the <head> with an all-or-nothing validator. If it encounters a single unsupported CSS selector (e.g. :has(), CSS custom properties, or an unclosed curly bracket), it deletes the entire style block.

The Fix: Always inline your core styles directly onto HTML tags, and sanitize embedded CSS with an AST linter.

Symptom: Fine print, copyright notices, or subheaders appear larger than headline text on mobile devices.

Root Cause: On mobile screens, WebKit and Blink heuristically “boost” font sizes below 13px to improve readability if they detect multi-column table layouts.

The Fix: Add -webkit-text-size-adjust: 100%; and -ms-text-size-adjust: 100%; to the <body> tag, and avoid font sizes under 12px.

Symptom: Dates, addresses, and phone numbers turn into bright royal blue text with underlines, breaking your brand palette.

Root Cause: Gmail scans text nodes for entities like “October 15” or “555-0199” and automatically wraps them in anchor tags.

The Fix: Wrap dates and phone numbers in anchor tags with explicit inline color: inherit; text-decoration: none;, or insert a zero-width non-joiner (‌) between digits.