How to Code HTML Email Newsletters

This article was first published in 2006, then re-edited in 2011 — and now it’s been re-re-edited in 2015.

HTML email newsletters have come a long way since this article was first published back in 2006. HTML email is still a very successful communications medium for both publishers and readers. Publishers can track rates for email opens, forwards, and clickthroughs, and measure reader interest in products and topics; readers are presented with information that’s laid out like a web page, in a way that’s more visually appealing, and much easier to scan and navigate, than plain text email.

Coding an HTML email is a fun, practical problem for programmers to solve. Unlike coding a web page, HTML emails need to display well on old email software — think Outlook or Mac Mail, as well as adapt to phone and tablet screens. I’ll show you how to create HTML emails that display well on any device, plus ideas to adapt your current HTML email code to display on phones and tablets.

This is actually the third revision of an article that was written and published on sitepoint.com in 2004, and includes new, up-to-date material that will help you ensure that your HTML email newsletters meet the requirements of today’s email clients.

HTML Email Fundamentals

The biggest pain when coding HTML email is that so many different software tools are available to read email, from desktop software such as Eudora, Outlook, AOL, Thunderbird, and Lotus Notes, to web-based email services such as Yahoo!, Hotmail, and Google Mail, to email apps on phones and tablets. The software used to render HTML for each email software tool determines what HTML and CSS code works and doesn’t work.

If you thought it was difficult to ensure the cross-browser compatibility of your web sites, be aware that this is a whole new game — each of these email software tools can display the same email in vastly different ways. And even when these tools do display an HTML email properly, accounting for variances in, for example, the widths at which readers size their windows when reading emails makes things even trickier.

Whether you choose to code your HTML email by hand (my personal preference) or to use an existing template, there are two fundamental concepts to keep in mind when creating HTML email:

Use HTML tables to control the design layout and some presentation. You may be used to using pure CSS layouts for your web pages, but that approach just won’t hold up in an email environment.
Use inline CSS to control other presentation elements within your email, such as background colors and fonts.

The quickest and easiest way to see how HTML tables and inline CSS interact within an HTML email is to download some templates from Campaign Monitor and MailChimp. When you open up one of these templates, you’ll notice a few things we’ll discuss in more detail later:

CSS style declarations appear below the body tag, not between the head tags.
No CSS shorthand is used: instead of using the abbreviated style rule font: 12px/16px Arial, Helvetica, you should instead break this shorthand into its individual properties: font-family, font-size, and line-height.
spans and divs are used sparingly to achieve specific effects, while HTML tables do the bulk of the layout work.
CSS style declarations are very basic, and do not make use of any CSS files.

My Code HTML Email site also has actual HTML emails I’ve downloaded and formatted so you can study to see how others created email.

Step 1: Use HTML Tables for Layout

That’s right: tables are back, big time! Web standards may have become the norm for coding pages for display in web browsers, but this isn’t the Web, baby. A few email software clients are light years behind the eight-ball in terms of CSS support, which means we must resort to using tables for layout if we really want our newsletters to display consistently for every reader (see the reading list at the end of this article for some excellent resources on CSS support in mail clients).

So put your standards-compliant best practices and lean markup skills aside: we’re about to get our hands dirty!

The first step in creating an HTML email is to decide what kind of layout you want to use. For newsletters, single column and two-column layouts work best, because they control the natural chaos that results when a large amount of content is pushed into such a small space as an email. Single column email designs also make it easy to display well on phones and tablets.

A single-column layout typically consists of:

a header, containing a logo and some (or all) of the navigation links from the parent web site to reinforce the branding and provide familiarity for site visitors
intra-email links to stories that appear further down in the email followed by the stories and content
a footer at the bottom of the email, which often contains links that are identical to the top navigation, as well as instructions for unsubscribing

Two-column emails also use a header and footer. Like a two-column web page, they typically use a narrow, side column to house features and links to more information, while the wider column holds the body content of the email. To get a two-column email layout to display well on a phone or tablet requires some code-fu, as you’ll see later in this article.

Promotional emails follow similar rules but contain much less in the way of content and links. They often include one or two messages, and sometimes make use of one big image with small explanatory text and some links below the image.

All of these email layout possibilities can be created easily, using HTML tables to divide up the space into rows and columns. In fact, using HTML tables is the only way to achieve a layout that will render consistently across different mail clients.

No matter how your email is designed, it’s important to remember the most important content should appear at or near the top of the email, so it is visible immediately when a reader opens your email. The top left of an email message is often the first place people look when they open an email.

This is the approach that I use to create HTML emails:

For a two-column layout, create one table each for the header, the two center content columns, and the footer — that’s three tables in all. Wrap these tables into another container table. Use the same approach for single-column layouts, but give the content table one column. This approach is especially suitable if the design of your email contains images that are broken up over multiple table cells. Otherwise, a single table with td rows for its header (with colspan="2" if the design uses two columns), content, and footer should display fine in all but Lotus Notes email software.
Use the attributes within the table and td tags to control the table’s display. For example, settingborder="0", valign="top", align="left" (or center, if that suits the design),cellpadding="0", cellspacing="0", and so on. This primarily helps older email clients to display the email in a (barely) acceptable way.
Even if the design of your email doesn’t include a border around your table, you might find it helpful during development to set border="1" to help with the debugging of any problems that arise with the internal alignment of tr and td tags. Change it back to border="0" for testing and production.

While this approach might offend purists who prefer to code using the latest standards, it is the only viable approach at this point. But the fact that we’re using tables for layout doesn’t mean we need to resort to old-school methods entirely. For example, no matter how poorly Lotus Notes displays HTML email, you should never have to resort to using the font tag. And while Outlook 2007’s HTML rendering engine is less than perfect, it does display basic HTML tables just fine.

There are some caveats, though; let’s take a look at styling our text next.

Step 2: Add CSS Styles

Did I say CSS support was poor in mail clients? Well, it is. But you can (and should) still utilize CSS for the styles in your email once your nested table layout is in place. There are just a few things to watch out for. Here are the steps that I use.

First, use inline styles to store all of your style information, as shown here:

<p style="color: red;"></p>

				1

						<p style="color: red;"></p>

This includes table, td, p, a, and so on.

Do not use the CSS style declaration in the HTML head tag, as you might when authoring web pages. Instead, place your style declaration right below the body tag — Google Mail, however, looks for anystyle declaration in the email and (helpfully) deletes it. Also, don’t bother using the link element to reference an external style sheet: Google Mail, Hotmail, and other email software will ignore, modify, or delete these external references to a style sheet.

For your container table — the one that houses the header, content, and footer tables — set the table width to 98%. It turns out that Yahoo! mail needs that 1% cushion on either side in order to display the email properly. If side gutters are critical to your email’s design, set the width to 95% or even 90% to avoid potential problems. Of course, the tables inside the container table should be set to 100%.

Put general font style information in the table td closest to the content. Yes, this can result in repetitive style declarations within multiple td cells. Put font style definitions into heading (e.g. h1, h2), p, or a tags only when necessary.

Use divs sparingly to float small boxes of content and links to the right or left inside a table’s td cell. Google Mail, for one, seems to ignore the CSS float declaration (yet Yahoo! and Hotmail cope with it just fine). Sometimes it’s better to code a more complex table layout than to rely on the float declaration. Or, since it’s all too easy to clutter up an email, ask your designer to put the floated content in the narrow side column instead. Flaky support for floats is one issue that may cause an email design to be reworked.

While divs appear to be barely useful, spans appear to work almost every time, because they’re inline elements. In some cases, spans can be used for more than just coloring or sizing text: they can be used to position text above or below content.

Note that some email delivery services will unpack style definitions to make them more explicit and, therefore, more readable by all email software. For example, the CSS shorthand style="margin: 10px 5px 10px 0;"may be expanded into the long style declaration shown earlier. Test each email and look to see what happens to the email code. Start with CSS shorthand because, in the worst case, it appears to work well with all email software.

If you’ve downloaded and studied the email templates from Campaign Monitor and MailChimp, you’ll see that they treat the container table as if it were the html body tag. The Campaign Monitor team refer to this table as the “BodyImposter,” which is a great way to think about the frame or wrapper table. From a CSS perspective, the container table does what the html body element would do if services like Google Mail didn’t disable or ignore the body tag.

Step 3: Adopt Best Practices

Knowing that you’ve created valid HTML email using the guidelines I’ve suggested is only part of the solution — there are several best practices that you should follow to ensure that your email is well received.

The next step is to test your HTML email in a variety of email clients. Often this will identify problems that require workarounds.

The first test tools to use are the Firefox and Internet Explorer web browsers. If the email displays well or perfectly in both browsers, there’s a good chance testing the email in Outlook, Yahoo!, Google Mail, and other services will reveal only minor problems. If possible, I’d also recommend testing your email in Internet Explorer 6 — this should give you a good indication of how your email will render in Outlook 2003 (refer to the list of resources at the end of this article for information on running Internet Explorer 6). Finally, to test how email will look on an iPhone or iPad, check your HTML email in a Safari web browser.

Once the email appears fine in those two web browsers, use an email delivery service to send the email to a range of test email accounts. Ideally, this should include accounts with the Yahoo!, Hotmail, and Google Mail services.
The test accounts you use should, of course, be determined by the domain names in the mailing list of people who will receive the email. For example, if there are no AOL subscribers on this list, it’s probably a waste of time and money to set up, and test with, an AOL email account.

Here are the most common code tweaks that I’ve found necessary during this test phase:

Sometimes, a switch from percentage widths to fixed widths is needed. While this is not ideal — because readers can and do resize their email windows while reading — sometimes, using a fixed width is the only way to have a layout display properly in multiple email clients.
If there’s a spacing issue with the columns in the email design, first tweak the cellpadding andcellspacing attributes of the HTML tables. If that doesn’t work, apply CSS margin and paddingattributes. HTML spacing works better with older email software.
Image displacement can occur when a td cell is closed right below an img tag. This is an ancient HTML problem. Putting the </td> tag right after (on the same line as) the img tag eliminates the annoying and mystifying 1-pixel gap.

In addition, the following best practices are recommended:

Avoid using JavaScript. Most email software will disable it anyway.
If an image is sliced up and spread across several HTML table cells, test the email using many test accounts. Sometimes, it might look great in Outlook but be shifted by one or more pixels in Hotmail and other services. Also consider making the image a background image on a new HTML table that encases all of the table rows and columns that would display parts of your background image; this often achieves the same effect as slicing an image up, but uses less code and can provide better results (see below). Note that Outlook 2007 does not display background images; be sure to test your email code with your target email software.
For background images, use the table’s background attribute instead of using CSS. This works more consistently across email software than other potential solutions.
Store the email images on a web server — preferably in a folder that’s separate from your web site’s images (for example, in a folder called /images/email), and don’t delete them. Some people open emails weeks or months later, the same way people use bookmarks to return to web sites.
Be sure all your images use the alt, height, and width attributes. Setting values for these attributes improves results in Google Mail, as well as maintaining your layout when a reader has their images turned off. Note, however, that Outlook 2007 does not recognize the alt attribute.
Use the target="_blank" attribute for the a tags, so that people who read with webmail services don’t have the requested page appear within their webmail interface.
While a 1×1-pixel image can be used to force spacing to create a precise email layout, spammers often use 1×1-pixel images to determine if their email has been opened. Using this practice will increase the likelihood that your email is classified as spam.
Similarly, avoid using a large image “above the fold” in the email. This is another classic spammer practice and may cause your email to be interpreted as spam.

It’s important to make sure your HTML email displays acceptably with images turned off. Many email applications set the display of images to “off” by default. For example, if you use a background image to provide a background color with white font color over it, make sure the default background color for that part of the HTML table is dark, not white.

When I’m testing how an email displays with images off, I usually use my text editor to replace each image’ssrc attribute with a unique combination of characters such as “xsrcx”, and then revert it back again after the test.

Once the HTML email has been tweaked so that it displays well in your test email accounts, the next step is to go through a checklist. For example, verify the following:

Does the From address display properly (as a name, not a bare email address)?
Is the subject line correct?
Is the contact information correct and visually obvious?
Does the top of the email display the text, “You received this email because … Unsubscribe instructions are at the bottom of this email.”?
Does your email contain text asking readers to add your From address to their email address book?
Does the top of your email include a link to the web version of the message?

Many email delivery services include the ability to see how your HTML email displays in a wide range of email software. It helps you identify what code tweaks are needed before sending.

Step 4: Code for Google Mail, Lotus Notes, and Outlook 2007

Google Mail, Lotus Notes, and Outlook 2007 present their own unique coding challenges. Outlook 2007, believe it or not, has significantly less support for CSS than previous versions of Outlook!

Google Mail’s lack of support is a little more forgiveable — because the application runs in a browser, it cannot control the contents of the emails it displays. Consequently, Google’s engineers have had to take steps to ensure their application displays properly regardless of the quality of the HTML or CSS in which emails are written.

As a result, Google Mail acts like an artifact of the early 1990s, when web standards were primitive. It takes some work, but it is possible to crack open a Google Mail page and see just how convoluted their approach to rendering HTML email actually is.

For one thing, Google Mail deletes the CSS styles contained between any style tags, no matter where they appear in the email. And fonts displayed within HTML tables — the only alternative to using styles — have the odd habit of appearing larger than intended, no matter how the HTML email is structured.

The good news, however, is that if you code to account for the oddities of these three email applications, your HTML email code is likely to display well in most, if not all, email clients. Here are some techniques that appear to work well in Google Mail and other older email software:

Define the background color in a td cell with the bgcolor attribute, not the CSS style.
As noted above, use the background attribute in the td cell for background images instead of using CSS. One side-effect of this approach is that the background image can be made as tall as needed — if the content used in your email template is likely to vary in size, using an extra-tall background image in this way allows the height of the email shrink or expand, depending on the height of the copy, from one email to the next. Remember, though, that Outlook 2007 ignores background images completely.
If it works better, use the padding declaration to control margins within a td cell. The margin style does not work in these cells, but padding does.
If you need a border around a td cell, keep in mind that Google Mail displays a border around a tdcell when it’s defined in a div, but not when it’s defined as a border style in a td tag.
If you need a light-colored link against a dark background color, put the font definition in the td cell (so it applies to p and a tags equally) then add a color: style to the a tag.
If the p and a fonts appear to be different sizes, wrap the a tag in a p tag.
Google Mail aggressively uses the right-hand column of the Google Mail user interface, which squeezes the HTML email into the center panel. Be sure the padding style in the content tds is set to 10 pixels all round, so that text does not hit against the left and right edges.
When testing an HTML email with a Google Mail account, it’s likely that you’ll find that one or more font styles are missing in the td, h1, h2, p, a, and other tags. Inspect every font carefully to make sure Google Mail displays the fonts correctly.

Besides Google Mail, there’s another, less obvious hazard a programmer faces when creating HTML email: Lotus Notes. Many large corporations continue to support and upgrade their Notes installations.

Unfortunately, it’s impossible to tell which companies use Notes. The best approach is to follow the guidelines described in this article — the more primitive the code, the more likely it will work well, if not perfectly, with Notes.

That said, it’s quite possible Lotus Notes will introduce to your HTML email quirks that are almost beyond belief. For example, older versions of Notes can convert images to their proprietary formats, or simply ignore flawless basic HTML in one email, but display other HTML fine in another email.

Here are a few tips that will help you convince Notes to display your HTML email properly:

As we discussed previously, use a container table that contains all the internal layout tables (for example, for the header, content, and footer). This keeps the email together in one chunk of HTML, so pieces of the layout are less likely to wander when displayed in Notes.
Create a gutter around the container table by setting the width to a percentage and/or using a cellpadding of at least 5.
As I mentioned earlier, avoid using a style declaration in your email’s head tag. It might be the approach that adheres to web standards, but Notes (like Google Mail) might delete your styles. Rely, instead, on inline styles within the table, td, h1, h2, p, a, and other tags.
Use absolute URLs to images stored on a web server. You can’t do much about Notes converting images, but using remote images might help.
Intra-email links, using named anchors, rarely (if ever) work in Notes. It’s simply best to avoid links that jump down the email to a specific piece of content.
Avoid colspans in your HTML tables. Notes — especially its earlier versions — can deal only with basic table layouts.
Be sure that your td cell widths are accurate. Unlike web browsers, which automatically set all cells to the widest-defined width, Notes sizes each td cell based on its defined width.
Centering an email layout usually won’t work in Notes. Email layouts generally have to be left-aligned.

Using these techniques to achieve a successful render in Google Mail and Lotus Notes will ensure that your emails also display fine in Outlook 2007, which uses an older HTML rendering engine. Microsoft has published details about what their email software will and won’t display properly; more details can be found in the Resources section at the end of this article).

Campaign Monitor, an email delivery service, has a comprehensive list of CSS elements support for every popular mobile, web and desktop email client.

Step 5: Coding for Phones and Tablets

An amazing number of people read HTML email on their smart phones and tablets, as well as their desktop email software. Adapting your HTML tables to display well on these devices turns out to be somewhat easy. It helps CSS support is very good for the HTML rendering engines used on new phones and tablets.

The solution is to use the CSS @media definition to target the HTML table TD cells and boost the font sizes needed to display well. For example, fonts on an iPhone need to be 13 pixels to be legible. The best part? Webmail and desktop email software will either strip out or ignore your @media definitions while your phone and tablet will read the code and display everything perfectly.

Here’s a sample set of @media definitions to display a one-column layout HTML table for phones and tablets:

@media only screen and (max-width: 480px) {
  /* mobile-specific CSS styles go here */
  table[class=email], table[class=email-content] {
    clear: both;
    width: 320px !important;
    font-size: 13px !important;
  }
}

				
					
				1
2
3
4
5
6
7
8

						@media only screen and (max-width: 480px) {
  /* mobile-specific CSS styles go here */
  table[class=email], table[class=email-content] {
    clear: both;
    width: 320px !important;
    font-size: 13px !important;
  }
}

					

			

Place this @media code directly below your body tag class="email" to your table definition andclass="email-content" to your TD cells. When your HTML email is viewed with a device (or web browser horizontally re-sized) less than 480 pixels, these definitions will activate.

The secret to coding a two-column HTML email to adapt to small phone and tablet screens? Put each column into its own table. Next, for each HTML table, use inline CSS to float: left and HTML align="left" to float and align each content column table to the left. Then add class="email" to your table definition andclass="email-content" to your TD cells.

With the @media code above, for screens less than 480 pixels wide, this will set the column tables, your left and right columns, the same width as the left content column and slides under the main column.

This approach can be used to target any layout design changes to work with phones and/or tablets.

This solution comes from an excellent guide from Campaign Monitor, Responsive Email Design, which has even more details and ideas about how to make HTML email responsive to different screen sizes.

Summary

Many people who receive email prefer HTML over text for a number of reasons. For programmers, though, the task of creating an HTML email that will display consistently appears both simple and horribly complex. This article has described many of the issues and strategies for creating markup that will work across email software.

What’s the best idea to take away from this article? If there’s a choice to be made between a simple email design and a more complex solution, simplicity is always the safest bet.

How to Code HTML Email Newsletters

HTML Email Fundamentals

Step 1: Use HTML Tables for Layout

Step 2: Add CSS Styles

Step 3: Adopt Best Practices

Step 4: Code for Google Mail, Lotus Notes, and Outlook 2007

Step 5: Coding for Phones and Tablets

Summary

Further Reading

A Guide to Email Marketing Best Practices for 2019

HTML Email Fundamentals

Step 1: Use HTML Tables for Layout

Step 2: Add CSS Styles

Step 3: Adopt Best Practices

Step 4: Code for Google Mail, Lotus Notes, and Outlook 2007

Step 5: Coding for Phones and Tablets

Summary

Further Reading

A Guide to Email Marketing Best Practices for 2019

Related posts