Some of the tough features of HTML electronic mail coding is that each electronic mail consumer has its personal quirks and options. E-mail shoppers normally find yourself with these quirks by way of the perfect of intentions. For instance, they may flip a plain textual content web site deal with right into a clickable hyperlink. There’s additionally the difficulty of safety. E-mail shoppers must be sure that our electronic mail’s HTML and CSS received’t intervene with their very own interface’s HTML and CSS. A malicious electronic mail may use sure CSS properties (like absolute positioning) to lure folks into clicking on overlaid hidden hyperlinks. So electronic mail shoppers ought to parse, filter and manipulate HTML electronic mail code. However which means that we, as electronic mail builders, should concentrate on this and make our code as pleasant as attainable for them.

From options to bugs, listed below are among the hottest suggestions and methods we have to know. This text is excerpted from Crafting HTML Email, availble on Pylogix Premium.

Supporting the Outlooks

Based on electronic mail analytics instrument Litmus, Outlook (on each Home windows and macOS) accounted for 4.44% of email client market share in January 2022. That will not appear a lot, and bear in mind to take email analytics with a pinch of salt, however chances are high you’ll meet Outlook on Home windows sooner or later in your electronic mail developer journey.

Right here’s what it’s worthwhile to know to make your HTML emails work painlessly within the Outlooks on Home windows.

How the Outlook Rendering Engine Works

Since 2007, the Outlooks on Home windows have used Phrase because the rendering engine for HTML and CSS. Microsoft justified the use of Word in 2009:

We’ve made the choice to proceed to make use of Phrase for creating e-mail messages as a result of we imagine it’s the perfect e-mail authoring expertise round, with wealthy instruments that our Phrase clients have loved for over 25 years.

Not solely is Phrase not superb for rendering HTML and CSS, however the documentation on the matter is abysmal. The one official present documentation about Phrase’s rendering is a 2006 publish from Microsoft explaining HTML and CSS rendering capabilities in Outlook 2007.

It consists of info on the next:

  • CORE: colour, background-color, textual content properties (font, font-family, font-style, font-size, font-weight, text-decoration, text-align, vertical-align, letter-spacing, line-height, white-space), border shorthand properties (border, border-color, border-style, border-width, border-collapse) and a few others.
  • COREEXTENDED: text-indent and margin properties (margin, margin-left, margin-right, margin-top, margin-bottom).
  • FULL: width, peak, padding (in addition to padding-left, padding-right, padding-top, padding-bottom) and border longhand properties (border-left, border-left-color, border-left-width, border-left-style, and so forth).

And every of those classes will solely apply to sure HTML parts:

  • <physique> and <span> solely assist CORE properties.
  • <div> and <p> assist each CORE and COREEXTENDED properties.
  • All the opposite parts supported by Outlook (like <desk>, <td>, <h1>, <ul>, <li>, and so forth) assist CORE, COREEXTENDED and FULL properties.

This implies we should take into consideration which component to make use of to use sure types. So if now we have to outline a width or a peak on a generic container component, we’ll use a <desk>. If we want padding, we’ll additionally use a <desk> and a <td>.

To at the present time, the Outlooks on Home windows are the only cause we nonetheless use tables in HTML emails. Fortunately, there are methods for us to solely make these tables seen for Outlook, hiding them from extra succesful electronic mail shoppers and permitting us to make use of extra semantic code.

Microsoft launched conditional comments again in 1999 in Web Explorer 5. They have been fairly standard on the Net in the course of the IE6–9 period, however they have been eliminated for Web Explorer 10 and 11. Right here’s the way it works: inside an everyday HTML remark (<!-- -->), you may code a situation that may make the remainder of the content material seen if that situation is fulfilled. Right here’s an instance:

It seems that conditional feedback are additionally supported within the variations of Outlook on Home windows utilizing Phrase’s rendering engine. As a substitute of utilizing IE as a situation, we’re going to make use of the mso key phrase:

Circumstances can be tied to a model quantity. For instance, mso 12 targets Outlook 2007. Sadly, Microsoft has stopped incrementing this model quantity within the newest Outlook releases. So mso 16 targets each Outlook 2016 and the latest Outlook 2019.

We are able to additionally use operators like gte (better than or equal) or lte (lower than or equal) to create extra advanced situations:

One other helpful operator is the NOT operator (!), which lets us insert code for each electronic mail consumer besides Outlook on Home windows:

<p>That is seen in each electronic mail consumer besides the Outlooks on Home windows.</p>

mso- Properties

Outlook on Home windows has a whole lot of proprietary CSS properties, largely recognizable due to the mso- prefix. An entire listing is offered in a .chm file, however electronic mail developer Stig Morten Myre has a handy archive of it readable online.

For lots of normal CSS properties, Microsoft has an equal proprietary model prefixed by mso- and suffixed by -alt. For instance, we will outline a padding worth for simply Outlook on Home windows with the mso-padding-alt property. A method I usually use that is once I code buttons. Ideally, all the seen space of a button needs to be clickable, so I usually add padding to <a> parts. However Outlook on Home windows doesn’t assist this. So as a substitute, I wrap every <a> component with a <desk> and apply a padding just for Outlook on Home windows with the mso-padding-alt property:

<desk border="0" cellpadding="0" cellspacing="0" function="presentation" align="middle" model="margin:0 auto; max-width:100%; background:#2ea44f; border-radius:5px; border-collapse:separate;" class="email-btn">
        <td model="mso-padding-alt:14px 16px; text-align:middle;">
            <a model="padding:14px 16px; show:block; min-width:128px; colour:#fff; font:daring 16px/20px Helvetica Neue, Roboto, sans-serif; text-decoration:none; text-align:middle;" href="" goal="_blank" >Name to Motion</a>

Outlook additionally has different unprefixed proprietary properties that may mimic their extra trendy CSS equivalents. For instance, text-underline-color in Outlook is identical as text-decoration-color in CSS. So if you wish to apply a selected colour to a textual content underline, you need to use each properties:

text-underline-color: pink; 
text-decoration-color: pink; 

Stig Morten Myre has an important article explaining how to fix bugs with Outlook specific CSS, together with recommendations on the way to use mso-text-raise or mso-line-height-rule: precisely.


VML is SVG’s ancestor, crafted by Microsoft within the late nineties. Identical to SVG, you may draw content material with markup code. For instance, if we need to draw a pink rectangle, we will use the <v:rect> component and the next code:

<v:rect xmlns:v="urn:schemas-microsoft-com:vml" 
        model="width:200px; peak:100px;">

A prerequisite for getting VML to work in Outlook on Home windows is so as to add its namespace declaration (xmlns:v="urn:schemas-microsoft-com:vml"). It might probably both be repeated inline for every VML component we use, or it may be added on the <html> component solely as soon as. And since VML will solely work in Outlook on Home windows, we’ll ensure that to wrap it in a conditional remark. Right here’s a full working instance for our earlier pink rectangle:

<!DOCTYPE html>
<html lang="en" xmlns:v="urn:schemas-microsoft-com:vml">
    <title>VML rectangle</title>

In fact, we will do extra thrilling issues than pink rectangles. A method we will use VML is to faux properties unsupported by Outlook on Home windows — similar to background photographs. If we need to present a background picture on our <physique> component, we will use the <v:background> element. Nonetheless, this is perhaps a supply of accessibility points, because it turns the content material inside it into a part of the VML picture, which could get misplaced for assistive applied sciences like display readers.

Marketing campaign Monitor’s and make in depth use of VML to faux background photographs or rounded corners. And electronic mail developer Mark Robbins supplies nice examples of how VML can be utilized to create CSS triangles or fake absolute positioning.

Microsoft’s “How to Use VML on Webpages” and “VML Object Model Reference” are nice locations to begin studying about VML.

Rendering at 120dpi

On sure Home windows configurations, Outlook on Home windows applies DPI scaling on emails. E-mail developer Courtney Fantinato has an in depth information to correct Outlook DPI scaling issues. Listed here are the three guidelines it’s worthwhile to comply with:

  1. Add the Microsoft Workplace namespace on the <html> component:

    <html xmlns:o="urn:schemas-microsoft-com:workplace:workplace">
  2. Add the next OfficeDocumentSettings declaration contained in the <head> component:

  3. All the time use dimensions outlined in CSS as a substitute of HTML attributes:

    <desk align="middle" function="presentation" width="600"></desk>
    <desk align="middle" function="presentation" model="width:600px;"></desk>

The one exception for that is with photographs. In Outlook on Home windows, a width set in a model attribute is ignored on photographs.

Making Your Emails Work with out <model>

In relation to making use of types to any HTML content material (be it for an internet web page or an HTML electronic mail), there are 3 ways to do it, utilizing:

  • a <hyperlink> component and an exterior stylesheet
  • a <model> component
  • an inline model attribute

E-mail shoppers are very opinionated relating to this, and assist for every of those methods can range wildly. That is normally resulting from safety points. E-mail shoppers should be very cautious in regards to the types they permit, as a result of a malicious electronic mail may use types to deceive a person. For instance, utilizing mounted or absolute positioning may let a malicious electronic mail developer stack faux parts over an electronic mail consumer’s personal interface.

E-mail shoppers make use of quite a lot of strategies for getting round this, similar to solely permitting a subset of properties or values from a secure listing of their very own. Additionally they apply prefixing to CSS selectors in an HTML electronic mail to stop electronic mail types from impacting the consumer’s interface. For instance, a selector like .button {} would turn out to be .rps_1234 .x_button {} in

The <hyperlink> component is very well supported in desktop native functions like Apple Mail (on macOS or iOS) or Outlook (on Home windows or macOS). Nonetheless, it’s virtually universally ignored by webmail shoppers (similar to Gmail,, Yahoo Mail, and so forth) in addition to plenty of cellular apps (like Gmail, Outlook or Yahoo Mail, on both iOS or Android). So it’s not a beneficial approach to model an HTML electronic mail. However it will probably have fascinating use instances, like when Litmus created a live dynamic Twitter feed in 2015.

The <model> component has way better support. Nevertheless it additionally has a couple of quirks. Gmail shoppers, specifically, solely assist model tags outlined within the <head> (not within the <physique>). They’re additionally very choosy about any syntax error, and Gmail will take away a whole <model> that accommodates one thing it doesn’t like (like an @ in an @ declaration, for instance). It’s a standard apply to make use of a number of <model> parts in HTML emails. After eradicating the unsupported ones, Gmail will mix them right into a single one which’s limited to 16KB.

However <model> parts are usually not at all times supported. For instance, when you obtain an electronic mail within the Gmail app (on iOS or Android) with a non-Gmail deal with (like an or Yahoo deal with), you received’t get <model> assist.

<model> parts can be eliminated contextually. For instance, once you ahead an electronic mail within the desktop webmail of Gmail, all <model> tags are eliminated. Gmail additionally removes <model> tags when an electronic mail is seen in its unclipped model.

In order a normal rule, it’s safer and extra strong to make use of inline types through the HTML model attribute. We are able to additionally use <model> tags, however solely as a progressive enhancement, particularly for issues like @media queries or :hover pseudo-classes that may’t be inlined.

“Making an electronic mail work” with out the <model> component can imply plenty of various things. Nevertheless it’s finest to suppose at the start in regards to the following:

  • Structure. An electronic mail with out <model> ought to modify to any width with out horizontal scroll. I normally take into account going as little as 280px huge, which displays the width of an electronic mail seen on Gmail on an iPhone SE.
  • Branding. An electronic mail with out <model> ought to mirror the branding of the sender.

E-mail shoppers robotically add hyperlinks to sure key phrases. This may occur to the next sorts of textual content:

  • URLs (,
  • electronic mail addresses ([email protected])
  • telephone numbers
  • mailing addresses
  • dates
  • flight numbers

The picture beneath reveals how Apple Mail supplies detailed info on air flights when a present flight quantity is clicked.

Examples of automatically added links in Apple Mail

The issue is that, if we don’t plan for them, these hyperlinks will give you their default types (normally blue and underlined) — and this could create sudden and undesirable results. For instance, an computerized blue hyperlink on an already blue background can be unreadable. Sadly, anticipating these computerized hyperlinks isn’t foolproof. It’s not unusual {that a} customized supply or monitoring code is was a date or telephone quantity hyperlink.

Listed here are three attainable methods to keep away from computerized hyperlinks:

  • Add a selected meta declaration for Apple Mail. With this tag within the <head> of our electronic mail, Apple Mail received’t add computerized hyperlinks:

    <meta identify="format-detection" content material="phone=no, date=no, deal with=no, electronic mail=no, url=no">
  • Use a zero-width non joiner character. A zero-width non joiner is an invisible character represented by the entity &zwnj; (or &#847;) in HTML. We’ll use it right here to interrupt electronic mail shoppers’ content material detection algorithm by putting it in the course of textual content the place a hyperlink is perhaps added:

    Go to Sitepoint&zwnj;.com for extra particulars!
  • Add a hyperlink ourselves. E-mail shoppers are intelligent sufficient to not attempt to add a hyperlink to textual content that’s already linked. So if we add a hyperlink ourselves round textual content that we all know may get robotically linked, we will apply our personal types. A hyperlink would nonetheless be there, however at the very least not so prominently seen:

    Go to <a href="" model="colour:#000; text-decoration:none;"></a> for extra particulars!

Utilizing Actual URLs

Microsoft’s webmail has a bug when utilizing non-URL textual content because the href worth of an <a> component. For instance, take into account the next code:

<a href="" model="colour:blue;">Get the app on iOS</a><br>
<a href="TBD" model="colour:inexperienced;">Get the app on Android</a>

That is remodeled by into the next:

Get the app on iOS<br>
[TBD] Get the app on Android

Your complete <a> component, together with its types, is eliminated. And the worth of the href attribute (if it’s not empty) is added between brackets earlier than the hyperlink textual content.

I’ve been caught by this bug greater than as soon as, normally as a result of I didn’t have the hyperlinks to place there on the time I used to be coding. My go-to answer now could be to at all times use the consumer’s area or as a brief hyperlink. is one other helpful area that’s reserved by IANA “to be used in illustrative examples”.

Including an Empty <head>

Yahoo Mail on Android removes the <head> component of any electronic mail. That is very inconvenient, since which means that <model> tags, together with media queries, can’t work there. However it was discovered that the Yahoo Mail app will solely do that for the primary <head> of an electronic mail.

So which means that if we embrace a dummy empty <head> first in our code, after which hold our common <head> component, Yahoo Mail on Android will appropriately hold it and interpret it:

<!DOCTYPE html>
<html lang="en">
    <title>My E-mail</title>
        @media (max-width: 600px) {}

The picture beneath reveals an example email (courtesy of Actually Good Emails) within the Yahoo Mail app on Android. With out the double <head>, the e-mail is robotically scaled by the consumer. With the repair, the e-mail renders media queries simply as anticipated.

Screenshots in Yahoo Mail Android showing the rendering with and without the double head hack

Preserving E-mail Sizes beneath 102KB

Gmail’s desktop webmail has a infamous threshold of 102KB, after which it’s going to truncate an HTML electronic mail and present a “[Message clipped]” alert, together with a “View whole message” hyperlink. Whereas it’s unknown why this limitation exists and why it’s at such an odd quantity exactly, it’s been measured consistently across the years.

Screenshot of a clipped email in Gmail

This 102KB limits solely accounts for the dimensions of the HTML of our electronic mail message. It doesn’t embrace different components of an electronic mail (just like the plain textual content model, or all the MIME header fields). It additionally doesn’t embrace the burden of any distant asset like photographs or fonts. So if our HTML weighs 40KB with 500KB of photographs, we’re wonderful.

We need to keep away from this threshold as a result of:

  • Gmail will minimize our electronic mail at 102KB to insert its “[Message clipped]” alert, even when that is proper in the course of a <desk>. That is very more likely to break our electronic mail in sudden methods.
  • Behind the “View whole message” hyperlink, Gmail will present inferior assist for HTML and CSS. For instance, any <model> tag (and thus media queries) can be eliminated on this view.

A primary approach to measure that is to have a look at the burden of our HTML file in our working system. On-line electronic mail instruments like or Parcel additionally present an estimate of our code weight.

Remember the fact that some electronic mail service suppliers may course of components of our HTML in such a means that its weight will improve. For instance, CSS inlining or hyperlink monitoring might be massive offenders in making our code obese.

Optimizing our HTML electronic mail code might be finished in a number of methods. Right here’s what I normally take into account an important steps:

  • Minify your code. However don’t use a minifier constructed for the Net! HTML Crush is an effective one constructed for emails (avoiding making strains of code longer than 500 characters, for instance). Simply by eradicating indentations, you may diminish your HTML weight by a great third.
  • Take away unused code. In case your electronic mail is constructed from a generic template that features a lot of types for various parts, you may find yourself with types you don’t truly use. On-line instrument Email Comb cleans up unused code properly.
  • Be careful for CSS inlining. You probably have a CSS rule focusing on the common selector (for instance, * { colour:#000; }), this can be utilized to each single HTML component in your code (together with <tr>, <br>, and loads of different ineffective locations). Ensure your CSS inliner works as you anticipate and examine your code after inlining types.
  • Use fewer tables. Tables are crucial for Outlook on Home windows, however they are often heavy. If we’re not utilizing padding, border, or a number of columns, it is perhaps higher and lighter to easily have extra semantic bits of code stack on high of one another.

Gmail also can show the “[Message clipped]” alert with out actually clipping your message. This may be attributable to the presence of particular characters like © wherever in our message.

Yahoo and AOL shoppers have a specific bug with CSS comments. For instance, take into account the next code:

    .title {
        font-size: 32px;

That is remodeled by Yahoo and AOL into the next:

    #yiv1234567890 .yiv1234567890title {
        font-size: 32px;

The e-mail consumer renames each class by including a customized prefix (yiv1234567890) and provides a prefix to each selector (#yiv1234567890). This can be a quite common apply throughout electronic mail shoppers — particularly webmail variations — and is required to make sure that our electronic mail types can’t have an effect on the webmail consumer’s personal types, and vice versa.

The bug right here is that Yahoo additionally tries so as to add its prefix to the CSS remark. And since it solely provides it alone on a single line of code, this implies it applies to the CSS selector on the subsequent line. Think about the next selector:

#yiv1234567890 .yiv1234567890title { }

This now will get interpreted as follows:

#yiv1234567890 #yiv1234567890 .yiv1234567890title { }

With twice the id prefix, it not matches something on the web page, and thus this makes the CSS rule void.

This bug doesn’t apply if we’ve acquired CSS feedback inside a CSS rule (between the curly braces). However as a normal cautionary rule, it’s finest to take away all CSS feedback earlier than sending an electronic mail.

Utilizing an HTML5 Doctype

E-mail shoppers by no means output your HTML electronic mail code simply as is. They apply varied transformations, similar to filtering undesirable tags (like <script>), attributes and types. And webmail shoppers specifically don’t hold your whole HTML.

A webmail electronic mail is displayed in an internet web page that already has its personal doctype, <head> and <physique>, together with different meta parts. So a webmail consumer like Gmail seems for <model> tags in your head, compiles them right into a single one, and retains the content material of your <physique> component.

Because of this, in plenty of instances, you’ll find yourself with the webmail’s doctype, not yours. And these days, most webmail shoppers use an HTML5 doctype:

<!DOCTYPE html>

One aspect impact of the HTML5 doctype is that <img> parts have a line spacing beneath them. This turns into clearly obvious once you slice photographs.

The next picture demonstrates what occurs once you neglect to set show:block in your photographs in an HTML electronic mail (courtesy of @HTeuMeuleu on Twitter).

Screenshot of an email in Gmail with line spacing below images

There are numerous options for getting round this. Listed here are three, by order of private choice:

  • Add vertical-align:center in an inline model on the <img> component. (This may influence surrounding textual content if it’s worthwhile to align the textual content and picture in a different way.)
  • Add show:block in an inline model on the <img> component. (This adjustments the circulate of the content material and may influence sibling parts.)
  • Add font-size:0 to the dad or mum component of the <img>. (This may influence various textual content rendering.)

Right here’s an instance of the primary answer utilized to a picture with an inline model attribute:

<img src="emblem.png" 
     model="vertical-align:center;" />


Coping with electronic mail consumer quirks is a part of the job of an electronic mail developer. It’s a good suggestion to comply with electronic mail developer communities to comply with the newest updates and practices. I like to recommend the #emailgeeks hashtag on Twitter and the #emailgeeks Slack channel.

It may be powerful to maintain updated with the brand new quirks and likewise transfer past the outdated ones. In 2015, I launched a GitHub repository to track email bugs, a set of points with energetic discussions and potential options for all of the totally different electronic mail quirks and bugs. Over time, it has gathered over 100 points, 1 / 4 of which have since been mounted. This provides me good religion that by reporting what we see, electronic mail shoppers can enhance and repair their very own code. Whereas it’s a gradual course of, I do really feel like HTML emails are shifting in the direction of a greater future, with extra interoperability and requirements assist.

And that is nice information, as a result of this could open the way in which for extra enjoyable and thrilling options — similar to interactivity! In the next part of this book, we’ll take a look at how we will make our emails extra interactive with simply CSS and HTML.