HTML Email CSS Guide: Problems and Compatibility Considerations

Understand the Email CSS Processing Model

A web page usually loads in a browser context controlled by its developer. An email can pass through a template engine, inliner, sending service, security sanitizer, webmail application, native client, and user preferences. Browser support does not automatically transfer through that chain.

Google’s official Gmail reference says Gmail supports inline style blocks and standard CSS through a documented subset. Unsupported properties or selectors may be ignored. Prefer primary documentation where available and verify the production output in target clients.

Inline Styles and Embedded Style Blocks

Inline declarations attach essential presentation directly to an element. Embedded style blocks are easier to maintain for shared classes, pseudo-selectors, and media queries. Many workflows author classes, inline ordinary declarations at build time, and preserve responsive queries in the head.

Inspect the HTML after inlining. Specificity can change, duplicate declarations can increase payload, and an inliner may mishandle syntax it does not parse. Keep the readable source and generated output so defects can be traced.

Fixed Widths, Tables, and Overflow

Tables remain common for email structure, but fixed dimensions need a responsive plan. A 600-pixel desktop hint can coexist with width:100% and max-width:600px. A rigid 800-pixel cell can force horizontal scrolling on a phone.

Overflow declarations, positioned elements, negative margins, and viewport units deserve careful testing. Label valid features as compatibility considerations unless a parser proves them invalid. Measure the actual result at narrow widths instead of inferring every outcome from source.

Media Queries and Mobile Refinements

Media queries can change padding, type size, visibility, and column behavior based on width or orientation. MDN documents the CSS mechanism and Gmail documents supported query types. Neither establishes identical support across all email environments.

Prefer a fluid base, then add a small number of targeted queries. Keep essential content visible without them. Compare the states in a browser preview, then send to the required clients for approval.

Fonts, Backgrounds, and Decorative Effects

Provide a sensible font stack with a generic fallback. External web fonts create a network dependency and have varied client behavior, so the design must remain readable in a system font. Consolidate families where possible.

Background color is safer than depending on an image for meaning. When a background image is decorative, make the underlying color work alone. Treat gradients, filters, blend modes, shadows, and advanced effects as enhancements that need evidence for every important client.

A Practical CSS Review Method

First correct missing colons, malformed blocks, incomplete braces, and invalid values. Invalid CSS gives every renderer permission to ignore it. Next review variables, imports, positioning, overflow, widths, web fonts, and large style blocks as compatibility or maintenance concerns.

Finally inspect payload and repetition. Inlining naturally repeats declarations, so repetition is not automatically a defect. Remove only code that the sending workflow does not need and retest after each mechanical transformation.

Keep a small test matrix tied to the project’s real audience and record the source version, sending transformation, client, and observed result. That evidence is more useful than an unsupported universal-support statement and makes later regressions easier to reproduce.