Email on Acid’s Boilerplate for HTML Emails


Are you looking for a head start on fixing all the client quirks that emails encounter in the wild?

Try our boilerplate, and hit the ground running.

Email coding is a complex business. The code you’ll find below is not an email template. Instead the boilerplate is like a “foundation” for an email to render well in most clients. We’ve included tips, tricks and advice on how to code for every client from the get-go. You can copy the full text from the bottom of the code sample, or you can use the download button below to get both versions in a .Zip file.

If your screen isn’t wide enough to accomodate this code sample, feel free to download it and open it in your own text editor.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "">
<!--This is a great DOCTYPE to test with because it is used by Gmail and It is very important to test with and without 
a DOCTYPE because many clients strip it entirely - this effects paragraph margins & padding, centering, and box model padding.
For more information on how the DOCTYPE effects your email, check out the following resources:
Email on Acid -
Campaign Monitor -
***** BOILERPLATE  USE  *************************
This template is merely a guildline for writing HTML code that will render correctly across each of the most popular email clients.  
Please download the min. version of this code and as a general rule, avoid using comments in your final email campaign or else 
you may get blocked by spam filters.  Also, including a single quote in your CSS comments will cause your email to appear blank 
in Entourage 08.
Some of the embedded CSS used in this template can be adjusted based on your design but others need to be overwritten inline.  
You will find those instructions below.   
The CSS style block has been placed just above the closing body tag for Yahoo in IE7 & 8. This fix actually requires a DOCTYPE.  -->
<html xmlns="">
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <!--This content type tells a web browser how to interperet your special characters. However:
    EVERY EMAIL CLIENT WILL IGNORE THIS META TAG. Instead the content-type will be set in the header of your email.  The 
    header is created based on the server configuration which is controlled by your email service provider.  Here is more info:
    Solution: to avoid jumbled characters in your email, always use HTML entities.  Here's a free tool for quickly converting all 
    of your characters: 
    When testing, it's a good idea to try both:
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <meta http-equiv="Content-Type" content="text/html; charset=ISO-8895-1" />
    This will help you catch jumbled characters so that you don't forget to convert them to HTML entities.  -->
    <title>Your Message Subject or Title</title>
<style type="text/css">
                /****** EMAIL CLIENT BUG FIXES - BEST NOT TO CHANGE THESE ********/
                        .ExternalClass {width:100%;} /* Forces to display emails at full width */
                        .ExternalClass, .ExternalClass p, .ExternalClass span, .ExternalClass font, .ExternalClass td, .ExternalClass div {
                            line-height: 100%;
                            }  /* Forces to display normal line spacing, here is more on that: 
                        body {-webkit-text-size-adjust:none; -ms-text-size-adjust:none;} /* Prevents Webkit and Windows Mobile 
                        platforms from changing default font sizes. */
                        body {margin:0; padding:0;} /* Resets all body margins and padding to 0 for good measure */
                        table td {border-collapse:collapse;}    
                        /*This resolves the Outlook 07, 10, and Gmail td padding issue.  Heres more info:
                /****** END BUG FIXES ********/
                        p {margin:0; padding:0; margin-bottom:0;}
                                /* This sets a clean slate for all clients EXCEPT Gmail. 
                               From there it forces you to do all of your spacing inline during the development process.  
                               Be sure to stick to margins because paragraph padding is not supported by Outlook 2007/2010
                               Remember: does not support "margin" nor the "margin-top" properties.  
                               Stick to "margin-bottom", "margin-left", "margin-right" in order to control spacing
                               It also doesnt hurt to set the inline top-margin to "0" for consistancy in Gmail for every instance of a 
                               paragraph tag (see our paragraph example within the body of this template)
                               Another option:  Use double BRs instead... of paragraphs */             
                       h1, h2, h3, h4, h5, h6 {
                           color: black; 
                           line-height: 100%; 
                           }  /* This CSS will overwrite's default css and make your headings appear consistant with Gmail.  
                           From there, you can overwrite your styles inline if needed.  */
                       a, a:link {
                           text-decoration: underline;
                           }  /* This is the embedded CSS link color for Gmail.  This will overwrite and Yahoo Beta's 
                           embedded link colors and make it consistent with Gmail.  You must overwrite this color inline */       
               /****** END RESETTING DEFAULTS ********/
               /****** EDITABLE STYLES - FOR YOUR TEMPLATE ********/
                    body, #body_style {
                        font-family:Arial, Helvetica, sans-serif;
                        } /*The "body" is defined here for Yahoo Beta because it does not support your body tag. Instead, it will create a 
                        wrapper div around your email and that div will inherit your embedded body styles.
                        The "#body_style" is defined for AOL because it does not support your embedded body definition nor your body 
                        tag, we will use this class in our wrapper div.
                        The "min-height" attribute is used for AOL so that your background does not get cut off if your email is short.
                        We are using universal styles for Outlook 2007, including them in the wrapper will not effect nested tables*/
                      span.yshortcuts { color:#000; background-color:none; border:none;}
                      span.yshortcuts:focus {color:#000; background-color:none; border:none;}
                      /*When Yahoo! Beta came out, we thought we could put those days behind us but we might have celebrated a little 
                      too soon. Here's more: */
                      a:visited { color: #3c96e2; text-decoration: none} 
                      a:focus   { color: #3c96e2; text-decoration: underline}  
                      a:hover   { color: #3c96e2; text-decoration: underline}  
                        /* There is no way to set these inline so you have the option of adding pseudo class definitions here. They won't 
                        work for Gmail nor older versions of Lotus Notes but its a nice addition for all other clients. */
                        /*Optimizing for mobil devices - (optional)*/
                        @media only screen and (max-device-width: 480px) {
                               /* Here you can include rules for the Android and iPhone native email clients. 
                               Device viewport dimensions are as follows:
                               Iphone:  320px X 480px - portrait, 480px X 320px - landscape
                               Android:   350px X 480px - portrait, 480 X 350 - landscape
                              (These are average dimensions, the Android OS runs on several different devices)*/
                               body[yahoo] #container1 {display:block !important}  /*example style  */
                               body[yahoo] p {font-size: 10px} /*example style*/
                               /* You must use attribute selectors in your media queries to prevent Yahoo from rendering these styles.  
                               We added a yahoo attribute in the body tag to complete this fix. 
                               To learn more about media queries for mobile email, check out the following:
                        @media only screen and (min-device-width: 768px) and (max-device-width: 1024px)  {
                           /* Here you can include rules for the iPad native email client. 
                           Device viewport dimensions in pixels:
                                768 x 1024 - portrait 
                                1024 x 768 - landscape
                               body[yahoo] #container1 {display:block !important} /*example style*/
                               body[yahoo] p {font-size: 10px} /*example style*/                       
               /*** END EDITABLE STYLES ***/                      
                /*** EMBEDDED CSS NOTES ***
                        1.) Be aware that Gmail will not read any of your embedded CSS
                        2.) Although I have seen the !important priority used in other examples, it is not necessary.  
                        If you use "!important" you can no longer overwrite your styles inline which is required for Gmail.
                        3.) The Android does not support "class" declarations outside of the media query.  Here is more info on that: 
                        4.) You might want to consider duplicating your embedded CSS after the closing body tag for Yahoo! Mail in 
                        IE7 & 8.
                *** END EMBEDDED CSS NOTES ***/
<body style="background:#000; min-height:1000px; color:#fff;font-family:Arial, Helvetica, sans-serif; font-size:12px"
alink="#FF0000" link="#FF0000" bgcolor="#000000" text="#FFFFFF" yahoo="fix"> 
<!-- You may adjust each of the values above for your template as needed. 
We've included the style attribute for Gmail because it does not support embedded CSS and it will convert this body tag to 
a div. Since it gets converted to a div, the other body attributes like bgcolor are ignored.  
We included body attributes (alink, link, bgcolor and text) for Lotus Notes 6.5 and 7, as these clients do not offer much 
support for embedded nor inline CSS. 
The "min-height" attribute is set for Gmail and AOL since they will be converting this body tag to a div and we want our 
background color to reach the bottom of the page. 
The yahoo attribute is added if you are using media queries for mobile devices.  For an explanation, check out the media 
queries example in the style block below. -->
    <!--PAGE WRAPPER-->
    <div id="body_style" style="padding:15px"> 
    <!--This div is working as a wrapper and the body_style is picking up our CSS properties for AOL. The padding has been 
    included for Gmail, you can adjust this to your liking.
    If your email exceeds 23 inches in height, you might end up with unwanted horizontal spacing halfway down your email in 
    Outlook 2007 and 2010:
    The reason:
    The fix: Just change this wrapper from a div to a span and add style="display:block" - don't forget to change the closing tag 
    as well.  From there, stack your tables within your email so that no table exeeds 23 inches.  
    Here is another example:
        <!-- PAGE LAYOUT -->
        <table cellpadding="0" cellspacing="0" border="0" bgcolor="#000000" width="600" align="center">
                <td width="200">Content</td>
                <td width="200">Content</td>
                <td width="200">Content</td>
        <!-- Tables are the most common way to format your email consistently. Set your table widths inside cells and in most 
        cases reset cellpadding, cellspacing, and border to zero. Use nested tables as a way to space effectively in your message. 
        The bgcolor and width attributes for the Android Gmail application.  Gmail converts your body to a div, even on mobile apps. 
        Since there is no width set in your body, the Android sets the width of your converted body tag to that of the device viewport. 
        To make a long story short, your background color will get cut off as the viewer scrolls horizontally unless you add it to each 
        of your tables as well.
        In this example, we are using the align="center" attribute to center the final email, if you want it left aligned, just remove
        that.  Using align attribute will ensure consistant results in all clients even after your doctype is stripped.
        <!-- PARAGRAPHS -->
        <p style="margin-top:0"></p>
        <!--As stated above, paragraph tags are optional. Do not allow yourself to change the margin-top because it is not supported 
        in  Paragraph padding is hit or miss in Outlook 2007/2010.  You will have to stick to margin-left, margin-right, and 
        margin-bottom and avoid the generic "margin" property -->
        <!-- TEXT LINKS  -->
        <a href="http://www.emailonacid.html" style="color:#F00" target ="_blank" title="Email on Acid">Text Link Here</a>
        <!-- Here, we've used inline css to overwrite Gmail's default link color. -->
        <!-- EMBEDDING FILES -->
        <a href="http://www.emailonacid.pdf" style="color:#F00" target ="_blank" title="Email on Acid">External File</a>
        <!--If you have a client who asks you to include an attachement like a pdf, always recommend linking to an external file.  
        Attachements will often cause an email to be blocked by SPAM.-->
        <!--INSERTING IMAGES-->
        <img src="" alt="Info Here" title="Info Here" width="308" height="58"
        style="display:block"  border="0"/>
        <!-- Gmail, Yahoo and add in an extra space below images when using non IE browsers.  This is especially noticeable 
        when stacking images on top of each other.  
        A common fix is to add style="display: block".  Here are some more possible work-arounds:
        It's best to use the "align" attribute vs a CSS float if you are placing them inline with text - this is for Lotus Notes 6.5 and 7.
        Image widths and heights need to be explicitly set and actual dimensions must be correct for Outlook 2007 and 2010.  
        The alt and title tags are equally important because a majority of email clients block images by default and instead display 
        either the title or alt text.
        Use border="0" to avoid unwanted outlines around your images in various clients - especially when wrapping a link around
        the image.
        Last but not least, you must always use absolute references to images in HTML emails: 
        <table cellpadding="2" cellspacing="2" border="0"> 
                <td valign="top">•</td>
                <td valign="top">1.)</td>
        <!--Outlook 2007/2010 converts your list items into paragraphs and spans (particularly if you use inline styles) so although 
        using tables is rather frustrating, it might save you time and hassle when testing lists. -->
        <!-- BACKGROUND IMAGES -->
        <table cellpadding="0" cellspacing="0" border="0"> 
                <td valign="top" background="" bgcolor="#006600"> </td>
        <!--The "background" attribute within the TABLE, TH, or TD tag is the safest way to use background images.  This is supported 
        by all clients except Outlook 07, 2010, Lotus Notes 6.5, and 7.  For those, I added a "bgcolor" because Notes 6.5 and 7 have 
        limited support for inline CSS.
        If you want to display a background image in the body of your email, create a wrapper table, width 100%.  Again, this is 
        because Gmail does not support embedded css and if it finds a background image in your inline CSS, it will ignore the entire 
        style declaration.To get background images working in Outlook 07 and 2010, check out this article couresy of Campaign 
        Monitor and Brian Thies: 
        Just Beware: On some occasions the use of VML will completely lock up Outlook 07 and 2010 and we cannot make any claims 
        as to its SPAM implications.  We do plan to look into this further and we will update this template with our findings. -->
        <!-- EMBEDDING VIDEO -->
        <a href="" target="_blank">
            <img src="" alt="Online Demo" title="Online Demo" width="308"
            height="106" style="display:block;" border="0" />
        <!--In our experience, the best way to embed video is not to!  It is not supported by most email clients and it is highly likely to 
        get blocked by SPAM.  Instead, use an image with play button and link it to the actual video.-->
        <table width="150" cellspacing="3" cellpadding="0" border="0">
              <td width="150" height="35" align="center" background="
              button_back.gif" style="background-repeat:repeat-x; background-position:top left; background-color:#3c96e2; 
              border:1px solid #666666; color:#FFFFFF; font-weight:bold; white-space:nowrap; height:35px;">
              <a href="" target="_blank" style="color:#FFFFFF; 
              cursor:pointer; font-size:13px; text-align:center; text-decoration:none; vertical-align:baseline; font-weight:bold;"> 
              <span style="padding:10px 10px; color:#FFF">Online Demo ››</span></a></td>
        <!--This button looks good with and without images, here's more on that:>
    </div> <!--end wrapper-->
<!--As mentioned above, you might want to consider duplicating your embedded CSS after the closing body tag for Yahoo! 
Mail in IE7 & 8-->
<!-- Never include anything after your ending html tag because Comcast won't render it.
ONE FINAL NOTE: Your email will be opened across a variety of different platforms and web browsers.  Save yourself some 
time, test in all web browsers first.  Then be sure to preview your email in the most popular email clients using Email on Acid! -->

Happy coding!

Author: Kyle Lapaglia

Author: Kyle Lapaglia

16 thoughts on “Email on Acid’s Boilerplate for HTML Emails”

  1. Thanks Geoff, great work, I’ll be sure to use this to make sure I’ve not missed anything.

    Two additions i’d suggest is that

    1) Outlook 07+ will duplicate top and bottom padding across sibling table cells. It’s something thats given me a headache more than a few times.

    2) Adding min width to an inner container table can prevent android Gmail from auto-sizing.

  2. Thanks Sam!
    We’ll take note of those for our next revision of the boilerplate. Happy coding!

  3. I’m confused about one thing. Does the reset code, for instance for the headers, remain in the header, with the inline styles in the body. What I mean is I want my headers to be orange, but the reset sets them to black. If I use premailer, it will inline your reset styles, making the headers black, which I don’t want.

    I know. Dumb question.

  4. @Greg,
    If you want your headers to be orange, you should replace the color we specified in the boilerplate with the orange you’d like. This boilderplate is only meant as a baseline, you start from there and then make changes based on your needs. Hope that helps!

  5. @AJ: In Outlook 2013 you need to add styles for font-size and line-height that match your target height.

    So if for example you want a table row with a height of 5 pixels you just type your

    as follows:

    Hope this helps!

  6. Chris,
    Yes, this is the latest version. As stated in the article you linked to, attribute selectors are no longer needed, but they also won’t have a negative effect on your code. Hope that helps clear things up!

  7. @Steve,

    Our apologies for that! The zip file is back up and live. Let us know if you have any further questions.

    – Mallory

  8. When I send this email to mobile gmail client for the first time, it looks good. If I send this email second time, nested tables are not nested anymore and the layout is broken. Point to note is that I have a small part of text changing each time in email body (like first email saying “Test 1”, second email saying “Test 2”, etc.) so that the email is not considered “just the same email” by gmail and is not hidden fully. As far as I understand, gmail detects “duplicated” and “unique” content and puts “duplicated” one in a separate div no matter where that content was before. The only solution I’ve come up with for now is putting each line of text in it’s own table with inline style. Also workaround probably would be to change email subject so that they are not stacked in one conversation. Anybody has better solutions?

  9. Howdy! Would you mind if I share your blog with my twitter group? Theres lots of people that I believe would really enjoy your content. Please let me know. Thanks egdbdegcggckddaa

  10. @Smithe586 Absolutely! We’d love if your shared this to your audience.

  11. HI,

    In the if statement for MSO, maybe i’m wrong but there is nothing inside the of it. What is supposed to go in the if so the html looks correct?

Comments are closed.