Welcome to the next installment of our “Code Like a Boss, Revisited” series. Today, we’re going to focus on successfully using CSS in email. In my last post, we saw how it was beneficial to mainly stick with older methods of coding for layouts, i.e. tables. Unfortunately, that trend of writing code like it was 1999 continues when it comes to styling emails as well; modern CSS just isn’t supported as widely as we would like, and weirdly, even basic CSS isn’t supported in some cases. All in all, it can make for a bit of a challenge when designing email if you’re not aware of what works and what doesn’t, so let’s dive in and find out, shall we?

CSS that (Usually) Works in Email

For this post, I consider the feature to be “working” if it’s supported in at least 75% of major email clients, without any major caveats. This is, of course, entirely subjective.

Internal Style Sheets

Most email clients today at least partially support using the <style> tag to define internal style sheets in the <head> element of your email. Most macOS-based email clients enjoy full support, and Outlook on Windows has partial support. Gmail also offers partial support, but if you’re using the Gmail app with a non-Gmail account, it will not work. Note: Get ready to see that disclaimer a lot in this post. Gmail’s mobile webmail will strip it out completely, Gmail account or not.

Use of the !important keyword

The !important keyword is something that should be used sparingly due to its fundamental nature, but it does tend to be used more frequently in email development. While it is widely supported, there are a considerable number of frankly quite picky quirks associated with its use across the major email clients:

  • Gmail: Supported, but only if the keyword is written in lowercase.
  • Gmail app: Supported with the same lowercase caveat but use within inline style attributes is limited to non-Gmail accounts only.
  • Outlook on Windows: Supported in <style> blocks, but only with a space in front of it. Not supported within inline style attributes.

Backgrounds

Except for Outlook, which only supports setting a background color via CSS, email clients thankfully allow for most of the background CSS features to be used. Some of the more specific features, like background-blend-mode or background-size, are supported in the Gmail app only with Gmail accounts.

Borders

Basic borders are supported widely. Once you start looking at things like border-image or border-radius however, support drops off quickly.

Direction

The direction CSS feature enjoys 100% support in all major email clients, which is a rare feat. If you’re not familiar with it, it’s used to determine the writing direction used by the element’s text; either left-to-right (like English), or right-to-left (like Arabic).

Display

Display also enjoys 100% support, but 39% of that support is partial, with only certain display values being accepted. Your standard values of “inline”, “inline-block”, “block”, and “none” are supported across the board (the latter having an Outlook caveat); once you get into the more modern values, support lags.

Fonts

(Note: I’m talking about the CSS to control the display of fonts, and not the use of custom fonts; for more information on that topic, there’s a post for that.)

The font shorthand is another 100%-supported CSS feature, with two caveats:

  1. The Gmail app only supports it with Gmail accounts.
  2. Windows Outlook doesn’t support any font weights outside of “normal” and “bold”. Any font-weight values set between 0 and 599 are displayed as “normal”, and anything 600 or greater is displayed as “bold.”

Height

You might think this would be a no-brainer, but it’s not 100% supported in email. Windows Outlook only supports it on certain elements, and other email clients completely disregard it.

Width

Along with height, this should also be a no-brainer. Once again, Outlook on Windows is the problem child; it doesn’t support the property on <body>, <span>, <div>, or <p> tags. It also has a bug with regards to applying percentage widths to images where the computed display size is based on a percentage of the email’s width instead of the image’s containing element. Help to lock that down by including a “width” attribute on the image itself.

Margin

You would think that margin would be supported across 100% of email clients, but it’s only fully supported by roughly 76% of them. The things that aren’t supported are odd, but as usual, Gmail and Outlook on Windows are the problems:

  • Gmail doesn’t allow negative values for margins.
  • Outlook also doesn’t allow negative margins. It also doesn’t support margins on <span> and <body> elements, or use of the “auto” value. Rendering can also be problematic, as any assigned background colors are included inside the margin.

Padding

Oddly, padding is better supported than margin across email clients, with 95% having full support. A noteworthy quirk is that Outlook on Windows only supports its use on <td> or <th> elements, and the largest vertical padding applied to a particular table cell will be applied to all the cells in that row.

Letter spacing

The letter-spacing property enjoys 95% full support, and 5% partial support among the major email clients. Outlook on Windows prevents a full 100% score here, with problematic rendering when large negative values are used, and smaller-than-expected letter-spacing when using values with “em” units.

Line height

Like letter-spacing above, this feature is prevented from getting full support mostly by Outlook on Windows. When using values with either “em” or “px” units, rendering can be weird; counteract the weirdness by including the Outlook-specific mso-line-height-rule: exactly rule.

List styles

The list-style shorthand property is mostly supported, with the following caveats for Gmail and Outlook:

  • Gmail will remove the entire property if list-style-image values are included.
  • Outlook on Windows only supports the list-style-type property; for list-style-position, you can use the Outlook-specific mso-text-intent-alt property instead.

Text alignment

Another one that you’d think would be widely supported, it’s only fully supported by 68% of major email clients, with the remaining 32% partially supporting. The Gmail app only supports the “start” and “end” values with Gmail accounts, and Outlook on Windows doesn’t support those values at all.

Text decoration

If you want to control your underlines on links, you’ll be curious about this one. Thankfully, it’s well-supported, with the only quirks being the now-standard Gmail app only supporting it with Gmail accounts, and Outlook on Windows not supporting multiple values, or the “overline” value.

Text transform

Supported by all major email clients, the only noted quirk is Outlook on Windows not supporting a transformation to all lowercase. But honestly, it would be easier to just enter the content in the appropriate case, wouldn’t it?

Units of measurement

The following units of measurement are usable by all major email clients:

  • Type size-based measurements: em, ex
  • Screen size-based measurements: px, % (percentage)
  • Print-based measurements: cm, in, mm, pc (picas), pt (points)

I realize that we’re getting into some granular stuff here, but if you’re really concerned about typography, these kinds of things matter.

Grouping CSS Selectors

One of the great things about CSS is the ability to group CSS selectors, separated by commas — e.g., .alpha, .bravo, .charlie — to apply the same styles to each. Luckily, 88% of email clients at least partially support this; the Gmail app only supports it for Gmail accounts, and Gmail’s mobile webmail doesn’t support it at all.

Other supported, commonly used CSS properties

  • max-height / min-height / min-width: These three are supported by everything except Outlook on Windows
  • max-width: Supported by almost everything except Windows Outlook versions prior to 2019; the latter only supports this property on <table> elements
  • outline: Supported by everything except Outlook on Windows. It’s also worth noting that email clients using the WebKit rendering engine will display outlines with square corners regardless of any other applied properties.
  • overflow: Apple Mail in macOS has some rendering/scrolling bugs on hidden content, and the property is not supported by Outlook on Windows, but works properly otherwise
  • vertical-align: Supported by all major email clients
  • white-space: Not supported by Outlook on Windows at all; supported in the Gmail app using Gmail accounts, except for use of the “pre” value. Otherwise, this is supported.

CSS to Avoid in Email

In order to successfully use CSS in email, we need to be aware that there are some notable CSS properties that either aren’t supported widely enough to be considered reliable, or don’t work at all. Most of these would fall under the CSS level 3 specification, more commonly known as CSS3. Much like HTML5, CSS3 is largely incompatible with email, along with some other advanced properties.

Let’s review some of the more commonly used advanced CSS properties with regards to their compatibility with email.

Flexbox and CSS Grid

Flexbox, if you’re not familiar with it already, is a CSS-based layout model designed to assist with positioning items in rows or columns (thus, one-dimensional), with the ability to control both the alignment and distribution of those items within their rows or columns. This sounds like it would be great for email, doesn’t it? Except, it doesn’t work, at least not as well as we would like it to.

According to research, 83% of email clients support the “display: flex” property, but that’s only part of the story. Outside of Apple Mail, very few clients support any of the flex-related properties necessary to change the default values that “display: flex” assigns to an element. So, while flex itself can be used across a good many clients, it’s going to be limited to out-of-the-box styling, which isn’t terribly useful.

CSS Grid is another method of layout that uses two-dimensional grids to position elements within a container. This would be an even better method to use with emails, except it’s even less supported than Flexbox. Latest research indicates that only 59% of email clients support it, which is disappointing. So, while you absolutely can use it for the email clients that support it, be sure to allow your layout to be able to gracefully fall back into a single column stacked layout for those clients which don’t support it.

CSS Animation

Animation support in email is primarily limited to Apple-based email clients, with Apple Mail and Outlook on macOS offering full support. With a few exceptions, no other email client supports it at all. So, if animation is that crucial to your message, you’ll need to stick with animated GIFs to ensure that you get the widest coverage possible.

CSS variables (AKA Custom Properties)

CSS variables are fantastic in website development because they allow developers to define custom values that can be reused anywhere in the document. For example, they can create a definition for a color, say “R1 Orange”, and set its value to the appropriate hex value for the desired color. The developer can then use that definition anywhere the color is needed instead of the hex value, and should the original value need to change, the developer can update it in one place instead of searching for every instance of it throughout the document.

Sadly, this is also primarily limited to Apple-based email clients for support. Gmail supports the function necessary to use the variables, but doesn’t support the functionality to declare the variables, which makes it useless.

Pseudo-classes and pseudo-elements

Very little support exists for any pseudo-classes or elements outside of Apple-based email clients.

Other commonly used CSS properties to avoid

  • box-shadow
  • aspect-ratio
  • :calc()
  • position
  • columns
  • transform
  • @font-face
  • @import
  • @supports

CSS that’s “Iffy” in email

There are several commonly used CSS concepts and properties that fall into the “it depends” category, depending on what you’re trying to achieve and what email clients you need to support. Let’s review some of the major ones.

Media queries

With today’s focus on mobile-friendly design, this is probably the most scrutinized CSS feature that developers look to use with email. Looking at the most recent statistics available, media queries are at least partially supported in 85% of email clients today, but they’re not supported at all by Windows Outlook, and only partially supported by Gmail, hence putting them into the “iffy” category. They also cannot be included in inline style elements, which further limits their usefulness.

So, if you do want to use them, use them in a progressive enhancement manner; meaning that if they’re supported, they enhance the email, but that the email isn’t relying on their presence to function properly.

Also, should you use them, limit the conditions that are applied to them to screen, min-width, and max-width, or omit them completely. Note that there’s also a media query that can be used to implement dark mode, but only 4% of email clients currently support it.

External stylesheets

Another common practice is to import CSS into documents using the <link> tag; this allows sizable stylesheets to exist outside of a document and be usable by multiple documents at a time. Unfortunately, outside of Apple Mail and (weirdly) Windows versions of Outlook, this isn’t supported by many email clients at all.

Custom fonts

While we’ve talked about using custom fonts previously in another post, an additional note is that if used, you should apply the font-family, font-size, and color properties to each table cell element in a table; otherwise, an email client may override your styling with its own defaults.

CSS Selectors

CSS Selectors are tricky, depending on what you’re looking to use. Most of them aren’t supported in the Gmail app with non-Gmail accounts, and Outlook on Windows only supports a handful. For example, general and adjacent siblings, child combinators, and the attribute selector aren’t supported at all. And the universal selector — e.g., “*” — isn’t supported by Gmail apps with non-Gmail accounts and Windows-based versions of Outlook.

Some additional notes on Outlook

You’ve seen that Outlook, especially on Windows, is extraordinarily problematic when it comes to application of CSS. While Apple Mail is by far the most used email client (58.55% as of June 2023), the majority of our clients continue to use Outlook on Windows, with versions of varying vintage. While the latest version of Outlook has switched to using Edge’s rendering engine, many companies are still using older versions of Outlook due to internal policies (and likely will for years, considering support for Outlook 2013 didn’t end until April of this year, and Outlook 2016 end of support is not happening until October of 2025), and thus we have to work around its various quirks, many of which involve CSS.=

We’ve already noted some specific cases, but there are some additional things to consider:

  • There are various MSO-prefixed CSS rules specific to Outlook that can be applied; we’ve covered some of them already, and here’s a full list
  • When using inline styling, be sure to use any available HTML attributes as well, like “align”, “valign”, “height”, and “width”. Remember, don’t include units when using these attributes; use percentages or numbers only
  • Images will need to have a “width” attribute applied to them so that they don’t expand to their full width, regardless of any CSS applied to them
  • Borders can only be up to 8px in size, and border radius is not supported. For the latter, use the VML RoundRect element instead
  • The “display: none” property applied to an outer table doesn’t apply to any nested tables inside it; each one will have to also have “display: none” applied to it. You can also use the “mso-hide: all” property to hide content from being displayed
  • Background images are supported via VML only, not CSS
  • You can use MSO conditional comments to define styling that should only apply to Outlook by enclosing it comments that only Outlook will parse

Putting it all together and successfully using CSS in email

Whew. To successfully use CSS in email, there are a lot of things to keep in mind. Based on everything we’ve learned above, let’s put some best practices in place:

  • Inline your CSS. Even though many email clients support using <style> blocks in the <head>, it’s a good idea to inline, or use “style” attributes, for all your CSS. This runs contrary to common web development standards and best practices, so it’s a bit of a mind-shift to get used to
  • Break up your <style> It’s been noted in the past that Gmail can have issues with large <style> blocks in the <head>, but there’s no real consensus on “how big is too big”. We recommend breaking large blocks up into smaller chunks, with the critical styles first, followed by chunks that progressively add enhancements to the email
  • Use responsive layouts that don’t rely on media queries. Since media query support is iffy, be sure that your layout can function without them; use them for progressive enhancement only
  • Stick to the basics. Use CSS level 2 properties as much as possible. If you want to use CSS3, check to make sure it’s supported, and build in fallback styling for email clients that might not support that feature fully
  • Test, test, test. Remember, once you send an email, you’re relying on the email client to render it as you intended; it’s out of your control at that point. That’s why it’s crucially important to test your layouts before deployment, especially if there’s any complicated or tricky layout at play. We recommend using an email testing service like Litmus or Email on Acid, which can display your email in most if not all the major email clients currently on the market, allowing you to easily check that your email is rendering as you anticipated.

It’s important to remember that emails likely aren’t going to look the same in every email client due to differences in rendering, and specifically due to varying support of CSS. We can get them close, however, by keeping the limitations in mind and designing emails accordingly.

Next time, responsive layouts

I mentioned responsive layouts several times over the course of this post; you might be asking “Okay Jeff, how do we create responsive layouts in the first place?” I’ve got you; we’ll discuss not only how to create responsive layouts, but also talk about different kinds of responsive layouts, and which ones may work best for your situation.

In the meantime, feel free to reach out to us if you have any questions regarding successfully using CSS in email, or any other front-end development questions you might have; we’re here to help!

References and further reading