How to prepare a HTML email for your web application

As many of my other posts in this blog, this will be a note-to-self, collecting all the tidbits that I have learned in preparing a HTML email that would show properly (or as expected) in major email clients during the development of my latest application.

Below is a short list of my suggestions.

• Use <table> and nested <table> instead of <div> for your layout
• Don’t create table cells with the height of 1px
• Don’t use <tr> to create top/bottom padding
• Don’t use <p>
• Use a <tr> for each paragraph
• Don’t rely on page level CSS
• Don’t try to put fancy styles in <a>
• Be careful when putting URLs in the email content
• Test as much as possible

There any many excellent articles on the same topic. I will try to collect them here in the future when I have more free time. In the mean time, if you know any good article, or have better solutions than what I have suggested, please feel free to comment below.

Use <table> and nested <table> instead of <div> for your layout

This might be counter-intuitive (and so much web 1.0) for lots of web folks because <table>, especially nested <table>, is usually considered not a good way to layout your web pages on modern web browsers. However, not every email client’s rendering engine is as powerful as that of your current web browser, and the number of CSS properties your email client understands is usually much fewer than that in your web browsers.
Another problem of using <div> with fancy CSS styles is that email clients on the web such as gmail.com usually strip down certain properties.
In my applications, I usually have one table that span 100% page’s width with just one cell as a container, and a nested table with fixed width and aligned in the center to contain the body of the email. You may also put borders around the inner table to have a nice wrap around your emails. Remember to set cellspacing and cellpadding of all table to 0.

Don’t create table cells with the height of 1px

I used table rows with cells of 1px in height to create a nice fading top and bottom borders for my email templates. That seemed to work in most email clients, but broke down in Outlook 2013 because the client seems to set a much bigger min-height for table cells.

Don’t use <tr> to create top/bottom padding

This might have a problem if you padding has background color. In Gmail app on Android, consecutive <tr> sections have a white border (or a 1px cell spacing) that will create a line between the padding and the content.
Instead, just use CSS padding property in your content <td>.

Don’t use <p>

You may feel bizarre on this as <p> is a very common tag on the web, especially when sematic web is getting more and more popular. However, certain email clients, e.g. Microsoft Outlook 2013 and the new Outlook Mail app on Windows 10, apply their own margins and paddings to p tags and other clients don’t, so it is hard to get a consistent layout when using <p>.
My suggestion is to use <span> instead or use no containing tag for text at all.

Use a <tr> for each paragraph

Without <p> as stated above, you will need someway to put spacing between paragraph. Using a table row for each paragraph may feel very messy at first but will save you much headache later. I have tried to put margin and padding inside <p>,<span> or <div>, but none works consistently across email clients.
Instead, putting padding inside <td> seems to work very well. So the idea is to have a <tr> for each paragraph and put padding CSS property in the inner <td>.

Don’t rely on page level CSS

Try to use inline CSS as much as possible. This causes lots of duplication in your email. However, it is the best way to make sure that the CSS style is applied since many email clients remove page level CSS.
There are some exceptions though, for example, a:hover and a:visited. You cannot set them inline, so page level is the best your can do here.
Besides, don’t reference an external CSS files. Again, not all email clients respect that, and some email clients block external files by default. This also introduces external dependencies for your email to display properly, which you will have to keep maintaining (which may also incur more bandwidth cost) as long as you want your sent emails to display correctly.

Don’t try to put fancy styles in <a>

I see many emails using “display:block” property on <a> tags to create buttons (I did the same at first as I learned the style from Bootstrap). However, this makes your email look bad on Outlook 2013 or the new Outlook Mail on Windows 10 as the email clients would ignore that display property (as well as margin and padding) and your buttons become links with tight background. You can see that problem in the notification email of WordPress:

Instead, try to use something like this:

I find that email clients don’t usually ignore or strip down styles of <td> tag (at least it did not happen in any of my tests), so your buttons are pretty safe this way, although that might look like an awful lots of code for just one button.
There are another way of using Word markups, but I feel pretty bad about that solution as your are creating even more duplication (for one button, you need one section for normal cases and one section for Outlook), and the Word markups are put inside a HTML comments and are not very friendly to HTML editors.

Be careful when putting URLs in email content

I realized this problem when one of my users reported that they could not use the link in the account activation email. As many other emails of the same kind, I put a button to activate user’s account and also an activation link in plain text so that our users can manually copy and paste that link into their web browsers in case the email client does not allow clicking on links.
Turned out some email clients such as Yahoo on old phone browsers try to XML encode the links and & becomes &amp;
This may not happen in most of your emails, but be extra careful when your emails have dynamic contents or special characters.

Test as much as possible

Finally, just as developing websites, try to make tests on as many email client as possible. Send yourself an email for each template that you have, and check that email on each client.
Here are some email clients that I usually test with:

• Microsoft Outlook 2013 and the new Outlook Mail app on Windows 10 (those two are quite similar except that Outlook 2013 is a bit more problematic)
• Outlook.com
• Gmail.com (many of your fancy style will be stripped out as gmail.com may also modify your inline styles)
• Yahoo.com (many of our users still use Yahoo Mail, so it is quite important)
• Email apps on mobile devices: Mail on Windows Phone 8.1, Outlook Mail and Gmail on Android, Mail and Gmail on iOS
• Web mail clients (gmail.com, yahoo.com, outlook.com) on old mobile devices (this is quite problematic as the clients might try to simplify your email for old devices)

I hope those help you to save some time creating your perfect email template. Any discussions or suggestions are much welcome!