1. Web Design
  2. Email

Say Hello to the HTML Email Boilerplate

Scroll to top
Read Time: 12 min

Figuring out html email will test the patience of any human being. A seemingly small formatting issue will inevitably arise and you think to yourself, "self, I'm a world class web developer type person schooled in the latest and greatest html5/css3/whatever, I can tackle this with plenty o' keystrokes to spare."

Several hours/cups of coffee/googling later, you are ready to pull your hair out and begin to contemplate what you would do to the person/persons who created {fill in the blank email client here}. That's pretty much why the HTML Email Boilerplate is around.

The HTML Email Boilerplate is a template of sorts that is absent of design or layout, that will help you avoid some of the major rendering problems with the most common email clients out there — Gmail, Outlook, Yahoo, etc. - the HTML Email Boilerplate

The boilerplate is here to provide you with some examples and helpful tips to keep your email design rendering as true-to-form as possible. You can use the boilerplate as a starting point to build your email. Or, you more advanced users may want to pick and choose specific snippets based on your needs.

In this article, we are going to breakdown some of the key aspects of the boilerplate and discuss how to implement it.

But before we get started, let's review some basic tenants of html email:

  1. The only thing you can reference externally are images. No external stylesheets, fonts, video (html5 is starting to change this though), etc.
  2. There is limited support for CSS elements across email clients (email client = Outlook, Gmail, Hotmail, Yahoo, etc.). You can check out a helpfull spreadsheet of what client supports what features here.
  3. Tables are most commonly used to layout an html email.
  4. And almost diabolical in nature, you need to test across email client, browser, and OS.

1: Setting the DOCTYPE

While many email clients strip out the doctype or don't allow for one at all, that doesn't mean we don't want to set one for our own testing purposes. In this case, the XHTML 1.0 Strict doctype is used mainly because two popular clients who strip out your doctype, Gmail and Hotmail, use it as the default.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "">

2: Working With Images

There are a few issues to be aware of when working with images in HTML email:

  • Linking images to another page can be tricky. Different clients will set unwanted (and ugly) borders around a clickable image.
  • Some email clients add extra space at the bottom of the image.
  • Because many email clients turn off images by default, the format/frame of your message can be distorted.

To combat these issues, the boilerplate sets up a few sensible defaults in the head of the document. It resets the borders around linked images to zero. It sets up a class (image_fix) to use when you don't want space underneath your images. The boilerplate also gives you an example of how to setup your images, always setting the width, height, alts, and titles; which help keep your format intact and consistent.

/* Some sensible defaults for images

		Bring inline: Yes. */
		img {outline:none; text-decoration:none; -ms-interpolation-mode: bicubic;} 
		a img {border:none;} 
		.image_fix {display:block;}

The boilerplate helps manage some of the issues you can run into when using images in html email. Bring these declarations inline to make sure your email will render as you intended it.

3: Tables, Tables, and More Tables

It's probably safe to assume that you have used tables before. I mean, tables have been around since the dawn of (internet) time. And while not the newest or coolest method around, tables are the most common framing tool for HTML email and a tried and true method to space effectively. Adding to that, nesting tables is a great way to group and separate content to conquer the most complicated designs.

The boilerplate sets you up with a few starting points for working with tables. The first is an outermost table (#backgroundTable) that acts as a container of sorts — stretching to the width of the viewable space in an email client. It's needed because some clients arbitrarily restrict the area to render - possibly resulting in oddly aligned content.

#backgroundTable {margin:0; padding:0; width:100% !important; line-height: 100% !important;}
<table cellpadding="0" cellspacing="0" border="0" id="backgroundTable">
		<td valign="top"> 

The #backgroundTable class helps reset some email client specific formatting while setting the canvas for you to work in.

The second (inner) table is centered and set to a pixel width of (600px), a good width to use to keep your email from stretching wider than an email client's viewable real estate (think preview pane).

Additionally, as it does for images, the boilerplate sets a few defaults for tables that help avoid formatting issues. The borders, cellpadding, cellspacing are set to zero and content is vertically aligned to the top of the cell.

Note: Because of limited support for div's in email clients, Tables are your best and sometimes only chance for formatting and positioning content.

4: Client Specific Fixes

Much of the reason this boilerplate, and others like it, exists is to thwart what seems to be random acts of sabotage at the hands of Yahoo, Google, Microsoft, and the like. Yahoo sets your paragraph margins to zero, jumbling your text together in one large blob. Gmail disregards (really, obliterates) any styling in the head of your document and screws around with your images. Hotmail hates your headers and Outlook has long been the bane of any HTML emailer's existence.

So the boilerplate tries to neutralize some of these nuances where possible, and mitigate the effect of the rest.

Specifically, for Yahoo, the boilerplate sets the paragraph margin to 1em in the head of the document and instructs to bring it inline. (more to come on "inlining" later)

p {margin: 1em 0;}


Yahoo Space IssueYahoo Space IssueYahoo Space Issue

To this:

Yahoo Space IssueYahoo Space IssueYahoo Space Issue

For Hotmail, the boilerplate overrides Hotmail's green header styling, normalizes the line-height, and sets a default width.

.ExternalClass, .ExternalClass p, .ExternalClass span, .ExternalClass font, .ExternalClass td, .ExternalClass div {line-height: 100%;}
h1, h2, h3, h4, h5, h6 {color: black !important;} /* or whatever color you want it to be */

For Outlook, the boilerplate sets "border-collapse: collapse" to get rid of some default padding.

Tip: By setting #outlook a {padding:0;} in the head your document, you can force Outlook to offer a 'view in browser' option. An interesting feature that would be awesome if other clients offered. (H/T Fabio Carneiro and MailChimp for this excellent snippet.)

5: Mobile

Mobile is one of the more exciting areas of building HTML email. While for the most part we are stuck in the 20th century from a markup perspective, new smartphones have given us a glimpse of what life could be like. Finally, we have a chance to play with "newer" web technologies. We can frolic in the fields of responsive design, we can query to our hearts content, and we can surely target different platforms. Okay, so maybe I got carried away a little but given the state of email, mobile is looking better every day.

With mobile rendering in mind, the boilerplate provides a good starting point for mobile targeting. It helps with font resizing (or stopping it). It helps to optimize your email for mobile by setting the viewport to the device's width. It also gives you the @media queries needed to target the iPhone (3+4), tablets (via resolution), Android phones, and a conditional statement for Windows Mobile.

Reminder: You shouldn't bring any styles declared in the @media queries inline.

6: Working with the EBP: When and How to Bring Styles Inline

Tools like Dialect's Premailer make inlining a breeze. A great tool for any html emailer to have in their chest, belt, or pocket protector.

As mentioned earlier, there are some clients that strip out your embedded styles in the header. We need to take another step from just having the embedded styles in the header and bring them inline. You can either do this manually, use your email clients built in tool (popular tools like Campaign Monitor and Mailchimp have them built in), or use a standalone tool like Premailer. Either way, follow the directions in the boilerplate to figure out what to bring inline.

To give you an idea of what we're talking about, look at the Yahoo paragraph fix mentioned ealier in the article. It has to be inlined to work. If not, your margin declarations will be ignored and your paragraphs will bunch together. On the other hand with another fix in the boilerplate, markup like table td {border-collapse: collapse;} that targets a padding issue in Outlook does not need to be brought inline. Outlook will respect your embedded styles (well, for the most part :)).

As an example, you would go from this:

p {margin: 1em 0;}
<p>Pellentesque habitant morbi tristique senectus ...</p>

To this:

p {margin: 1em 0;}
<p style="margin-top: 1em; margin-bottom: 1em; margin-left: 0; margin-right: 0;">Pellentesque habitant morbi tristique senectus ...</p>

Keep in mind that any styling in and right after the @media queries should not be brought inline. I would recommed removing the queried styles until you are happy with your email and then work them back in after inlining your other styles.

7: A Few Honorable Mentions

There are a couple topics that are worth mentioning but didn't make it to the boilerplate for one reason or another.

  • HTML5 Video: While really, really close, there are some major support flaws in Hotmail that made it awkward to include. There are some interesting tactics being tested now that can render an actual video in an email in a number of clients and gracefully degrade to a clickable image. However, Hotmail throws a little bit of a wrench in the whole thing as it will show the video and allow playback but without any visual controls. Right click works but that seems like a stretch to ask your readers to do. You could also set the video to autoplay - but could you really live with yourself doing that?

    html5 video

  • Facebook's Open Graph: Probably a candidate for the next release. I am still weighing the effect of having this in an email and specifically if there isn't a browser version of the email made available - should it be there?

    Facebook Open Graph

8: The State of Email

CSS3? Let's get to CSS2 first.

Many emailers lament that they have to code like it's 1999. Tables, not divs, reign supreme. CSS3? Let's get to CSS2 first. Email clients randomly support tags, declarations, and whole specifications. However, with the advent of iOS devices and some movement in the client space, rendering engines like Webkit are popping up and making life for emailers a little easier. Because of this and other factors, we are seeing some of the most intricate and beautiful designs ever. It's definitely an exciting time for emailers.

This movement has a ton to do with mobile, iOS devices in particular. As of June of this year, the second most popular email client was an iOS device. That means that we can use most anything a webkit browser will support to build our email - things like CSS3, HTML5, all come into play (woohoo). Don't get too excited though, you still have to account for very limited to no CSS3 or HTML5 support in many other desktop/web email clients (not woohoo).

With that said, this raising of the bar has definitely made an already complicated space more complicated. While some email clients are moving to web based standards, for example, Outlook on a Mac now uses webkit just like its Apple Mail counterpart, most desktop email and web based clients are moving to acceptable html/css support at a turtle-esque pace. So while mobile has shown us something of a light at the end of the tunnel, it has also added another column to the already crowded matrix of testing possibilities.

Like I mentioned earlier, this is definitely an exciting time for emailers. With so many great companies and individuals pushing the envelope for what's possible, it's inevitable (at least I sure hope so) that the momentum will push things in the right direction - and by "things" I mean better html/css support, a little standardization, and fewer headaches.


The boilerplate is here to showcase and highlight some of the pitfalls of developing for email and email clients. And while not exactly plug and play, with a little elbow grease, it will provide some helpful examples and snippets that will keep your email design rendering as true-to-form as possible. At the very least, it will save you some time googling and more importantly save you some hair.

I would love to hear back from you. If you have anything that you would like to see in the boilerplate, let me know here or @seanpowell.

Many Thanks

When it comes down to it, the HTML Email Boilerplate is simply a compilation of tips, snippets and best practices that have come across my desk and I would be remiss not to mention some of the great research and openness of Ros Hodgekiss, Brian Theis and the team over at Campaign Monitor; and to Fabio Carneiro and Mailchimp for the great work they do (and the great reset the boilerplate uses). The boilerplate is also put through its paces using two great email testing tools, Litmus and Email on Acid - without them, this would have been an impossible task.


Just a few that I use regularly...

Did you find this post useful?
Want a weekly email summary?
Subscribe below and we’ll send you a weekly email summary of all new Web Design tutorials. Never miss out on learning about the next big thing.
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.