What breaks in HTML email on Outlook and Gmail

An HTML email is not a web page. A browser renders a page with one of a handful of modern engines, but a message may be drawn by a word processor's engine, by a webmail service that rewrites your styles, or by a phone app that does both. The result is that a layout which looks perfect in a browser preview can arrive as stacked blocks, unreadable text or a blank rectangle. Four common habits from web design cause a lot of the damage: laying out columns with flex or grid, leaving all styling inside the head section, skipping the alt attribute on images, and setting text over a picture background that has no plain fill colour as backup. This guide explains why each one fails, in which client, and what to write instead.

Why email clients are different

The first fact to absorb is that a widely used desktop client did not use a browser engine at all. Microsoft documents that the message body in that release is drawn by the markup engine borrowed from its word processor, so whatever the word processor handles is what the mail client handles (Microsoft, Word 2007 HTML and CSS rendering in Outlook 2007). The page describes only a subset of an old HTML version and of the first CSS specification. Later releases of Outlook for Windows are listed together with it in the public support tables, and as general practice they are treated as sharing the same engine; check the current table for the versions your readers use.

The second fact is that webmail services are not one thing. Google documents that Gmail accepts a style block with most selectors and media queries, and warns that anything outside its list may just be dropped (Google for Developers, Gmail CSS support). The community support tables add the caveats that matter in practice: some behaviour differs for addresses hosted outside Google, and webmail services treat style blocks in their own ways.

So the working model is simple. Write for the weakest client you must serve, treat modern CSS as an improvement for clients that understand it, and make sure the email is complete without that improvement.

Habit one: columns made with flex or grid

On the web, putting two columns side by side with a flex container is routine. In email it is a trap. Microsoft's list of properties that the Word-based engine does not support includes the display property itself, along with float and the maximum and minimum width properties, and the page says that unsupported properties are treated as unknown (Microsoft). A flex wrapper therefore has no effect there: the two columns collapse into one stack, or lose their widths. The Can I email table for the flex value tracks Outlook for Windows release by release, and its notes add that Gmail's support does not extend to non-Google accounts and that the inline form of the value is not supported (Can I email, display:flex).

What does work everywhere is the old structure: a table, with rows and cells, and widths set on the cells. The same Microsoft page lists table, row and cell attributes such as width, height, background colour, padding and spacing as supported. A nested table is clumsy to write by hand, which is why most teams generate it from a template tool, but it is the one layout method every client agrees on.

If you want the columns to stack on a phone, add a media query that switches the cells to block display. That is an enhancement only. Clients that ignore the query still show a working two-column table.

Habit two: styles that live only in the head

The second habit is writing a tidy stylesheet inside the head and leaving the elements bare. It is tidy, and it is risky. The Can I email notes for the style element list several limits: no support inside the body, no support with non-Google accounts, a requirement in some clients that rules come after the style element that declares them, and a size limit of 16 KB on the style tag (Can I email, style element). The notes we saved do not name which client each limit belongs to, so check the live table for yours. If a client ignores the block, an email whose structure depended on it loses widths, padding, colours and font sizes together.

The safer arrangement is to write the structural rules directly on the elements: widths, padding, alignment, the main blocks' fill colours and the size of body text. Keep the style block for things that only improve the email, such as media queries and hover effects. A useful test is to delete the whole block and reload the message. If it is still readable and roughly in shape, the block is an enhancement. If it collapses, you have a structure problem.

Inlining by hand is tedious and error-prone, so many authors write normal CSS and let a build step or the sending tool copy the rules onto the elements. That step is common habit among authors, not a claim made by the pages cited here, and it is worth confirming that your tool does it for every rule you rely on.

Habit three: images with no alt attribute

Many mail clients block remote images until the reader allows them, and some readers use screen readers. In both cases the image is not seen, and the alt text is what remains. An image with no alt attribute shows nothing useful, or shows a file name. The Microsoft page lists alt among the attributes of the image element, so the attribute is part of the supported markup, not an extra (Microsoft).

The distinction that matters is meaning. A product photo, a logo or a banner that carries an offer needs a short text saying what it shows or says. A decorative spacer or divider should carry an empty alt, written as two quotation marks, which tells assistive software to skip it. Missing the attribute and writing it empty are different things, and only the second is correct for decoration.

Avoid turning a whole paragraph into a picture and expecting the alt text to carry it. Blocked images are common enough that important text such as a date or a button label should be real text in the message.

Habit four: text over a background image

A hero section with a picture behind a headline looks good in a design tool, and it is fragile in email. The Microsoft engine lists the background image property among those it does not support, so in that client the picture is never drawn (Microsoft). The Can I email table for the property carries a note that a picture can be placed there using the vector markup specific to that client, and further notes about partial and buggy behaviour in Gmail and other webmail: one note says the whole style attribute or style tag may be removed when it holds a valid image address (Can I email, background-image).

The consequence is a legibility problem. If the headline is white and the picture is dark, a client that drops the picture shows white text on a white page. The rule is cheap to follow: always set a background colour on the same element, chosen so the text is readable without the picture. Then the picture becomes a bonus. When a picture must appear in Outlook as well, use that client's special markup inside a conditional block, and test it, because it is easy to get wrong.

A short review you can run on any template

Open the source of the email and go through these steps.

1. Look for flex or grid declarations on wrappers. If the columns depend on them and there is no table, rewrite the layout as a table.
2. Read the style block. Ask what is lost if it vanishes. Move structural rules onto the elements.
3. Check every image element for an alt attribute. Decide for each whether it has meaning or is decoration.
4. Find every background image and check that the same element has a background colour and that the text reads on that colour alone.
5. Send a real test to a Gmail account, to a non-Google mailbox read in the Gmail app, and to a copy of Outlook for Windows, or use a rendering service. A preview in your editor proves little, because it uses a browser.

Removing the style block and watching the result counts as a real check because the outcome could be bad. Alt text is also an accessibility matter, and our write-up on an accessibility review where a model buried the fixes in advice shows why a short, specific finding is worth more than a long list.

When this does not apply

Scope first: only markup and styling are covered here, and the oldest vendor page used was written for a release from 2007 (Microsoft). It says nothing about delivery, such as sender authentication or spam filtering, and nothing about copy or links. The support information it relies on comes from a vendor page written for Outlook 2007, from Google's current page, and from a community table whose individual entries were tested on different dates; client behaviour changes, so check the live tables for the versions your audience uses. We did not render any email for this guide, so treat everything above as documented behaviour and common practice, not our own measurement. If your list is small and known, for example staff who all use one up-to-date client, you can relax some of the advice, and simple plain-text style messages need none of it.

Where our skill fits

Before a template goes to a sending tool, our html-email-compat-review skill reads the source of one email and reports four kinds of fault: flex or grid used for columns, structure kept only in the head, an image with no alt attribute at all, and a picture placed behind text without any fill colour next to it. For each it gives one line with the place, the client that breaks and the fix, and it ignores safe patterns such as an empty alt on a spacer. When nothing is wrong it says so in one line. It does not judge deliverability, copy or links.