I’ll Never Build Another Email Without The HTML Email Boilerplate Again!

I do a lot of HTML email development.  Every time I open my code editor to start working on an email, I cringe.

If you think cross browser compatibility is bad – try cross client compatibility.  Not only do you need to deal with a wide assortment of desktop clients from Lotus Notes and Entourage, to Outlook and Apple Mail, you also need to deal with a range of web mail interfaces from AOL Mail (I am as surprised as you are that it’s still in use) to Gmail – and multiple browsers for each of these. It’s a headache!

There is a lot of information and resources available on the web to help developers figure out what’s supported and what’s not for HTML and CSS in email clients, and like most developers I have developed my own basic template as a starting point, but I still had a lot of issues with various clients (namely Outlook 2007 and Outlook 2010), I was never able to figure out how to reset everything and work around all the issues (like the fact Hotmail changes all header tags to green).  I always wished there was a ready-made code base I could use as a starting point for email development.  Now there is!

Enter the HTML Email Boilerplate.  The HTML Email Boilerplate was created and is maintained by The Engage Group, and is similar to the popular HTML5 Boilerplate in that it gives you a very basic starting point, with CSS resets in place and a basic HTML structure to work from.  The boilerplate’s website says it “creates a template of sorts, 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 Mail, among others etc. …It will provide some helpful examples and snippets that will keep your email design rendering as true-to-form as possible.”  Perfect! That is exactly what I was looking for!

Jumping In

The boilerplate is very well commented, and it makes it easy to know what each chunk of CSS is for, and why you need it.  The comments include links to the original sources if you want to investigate more.  This really is a collection of the greatest tips and hacks all in one place, ready for you to use.

I’ve developed two HTML email newsletters so far this month, and used the boilerplate as the starting point for both.  When I first downloaded the boilerplate, I was bracing for a bit of a learning curve, but there really wasn’t any at all.  I had the boilerplate figured out in 10 minutes, and was “off to the races” building my email newsletter.

You won’t need to change what you are already familiar with for HTML email.  There is a little bit of HTML included, but it’s a standard table template that should be very similar to what you are using already.  Sadly all the ugly nested tables we are used to for HTML email will still be around to give you bad dream.  This code is useful, but not magical!

When you first get into the boilerplate, read over the comments in the CSS carefully.  While you will be mostly leaving the CSS that is already there alone and just writing your own below it, there are a few places where you need to edit the existing CSS – such as for changing link colors.  There are also some notes about what CSS code should be brought inline before sending, and which CSS shouldn’t or doesn’t need to be inline.
See my tip a little further down for an easy way to bring your CSS inline easily.

A Quick Fix

There is one issue with the code that I’ve come across, that makes images appear stretched vertically in Outlook 2000 only.  The fix for this is easy, you just need to remove one small part of the code.  Based on my testing this doesn’t affect any other email clients, so this change should be safe to make.  If you find out that this method breaks anything else, please let me know.

On line 41 of the boilerplate you’ll see this line:

img{height:auto; line-height:100%; outline:none; text-decoration:none;}

Change that line to:

img{outline:none; text-decoration:none;}

By removing the first two declarations, you’re removing the code that tells an image to stretch, and it should display at the proper size.

If you find any other issues, or have any questions about the boilerplate, check out the very lively Get Satisfaction community.

 Bonus  HTML Email Tip – Premailer

If you don’t have another tool to do it already, be sure to use Premailer before sending your email to move your CSS styles inline automatically, and get notified about any CSS you’re using that may cause problems across the various major email clients.

The comments inside the boilerplate tell you what you should move inline, and what you shouldn’t.  What I’ve been doing is saving a new version that has all only inline CSS (and my custom CSS) in place, sending it to Premailer, then copying the non-inline CSS back into my email.

In Conclusion

I won’t build an HTML email without using this code base again.  It’s saved me so many hours of debugging and tweaking to work across all the major clients.  It’s earned a permanent place in my toolbox.

Creating HTML emails couldn’t be any worse could it?  So why not try this out – all it can do is make it easier.

If you’re a web developer and you haven’t tried out the boilerplate yet, you’re wasting time fighting with the email clients.  Don’t wait any longer. Grab the HTML Email Boilerplate now!  Once you’ve become a devotee, join the Get Satisfaction community and help others, or get information on the next updates.


  1. sergio
    April 25, 2013 @ 4:44 pm

    hi dan
    i’m using this framework and my newsletter is greater than before but in outlook i’ve a little things to fix.

    could you help me with my code here, please? http://stackoverflow.com/q/16181339/1741735

    thanks a lot

  2. Jaap
    November 8, 2012 @ 2:21 am

    Hey Dan,

    What are you doing with the media queries? There’s a few conflicting views around in-lining CSS styles which obviously wouldn’t work for media queries.

    On a more generic topic, do you usually include a text-only version with your HTML emails?

    Also, I recommend using something like Sendgrid or Mandrill for emails since they help improve email deliverability rates and allow you to track open rates, click throughs etc without any effort.

    • Dan
      November 8, 2012 @ 11:50 pm

      Hi Jaap,

      I haven’t done a lot of work with media queries for mobile designs to be honest. I am planning to explore it in the next month or so more than I have, and will probably write an article then.

      I’ve looked at both Sendgrid, Mandril and a few other similar services. While they both look interesting, I haven’t had a scenario for using them yet. Most of my campaigns are done via Campaign Monitor.

      I plan to revamp the “Subscribe by Email” function for this blog very soon, so I’ll probably use one of these then.

  3. Adham Dannaway
    November 7, 2012 @ 5:58 pm

    Hi Dan,

    Thanks for the tips. I was also having issues in Outlook 2000 with vertically stretched images. Removing “height:auto; line-height:100%” did fix the image issue.

    It did however create a new issue for my responsive email template images. I actually use fluid images along with responsive tables to create a mobile friendly email and the fix above stops the images from resizing fluidly.

    I could simply fix my mobile friendly email width to 320px but it’s not as cool. Any ideas? Thanks =)

    • Dan
      November 8, 2012 @ 12:24 am

      Hi Adham,

      Sorry, I am not sure as I haven’t experimented with non -fixed width responsive email newsletters yet.

      All I can say is often times “cool” and “email newsletters” don’t go together. I just do whatever gets the job done.

  4. Marie McRae
    November 5, 2012 @ 4:28 pm

    THANK YOU! I work with submitted emails and other designers don’t test as far down as our requirements (Outlook 2000, 2003, 2007). I’ve been hitting my head against the keyboard trying to find this line of code (img{height:auto;) which has been wrecking havoc on the tests.

    I use Premailer all the time; while mostly good, it changes HTML code for trademarks and proprietary email service code. Some hand clean-up is always required.

    • Dan
      November 5, 2012 @ 9:07 pm

      I am glad I could help you out. That single line took me a long time to figure out.

      You should use Premailer before putting in any proprietary code, that helps a lot. I’ve never had an issue with it replacing the character entity values for trademark, but that should be a simple find and replace exercise afterwards.

  5. Jaap
    September 3, 2012 @ 11:00 pm

    Thanks Dan. I didn’t know about Premailer, it looks quite promising.

    • Dan
      September 3, 2012 @ 11:02 pm

      You’re welcome. Premailer is a great service to have in the “tool belt”. It makes things so much easier and quicker when developing HTML emails.