Designing HTML emails

Note: Instead of building your e-mails manually as described below, you probably want to use a tool like MJML.

The 90s are calling: they want their tables back. Unfortunately, you need them all for laying out your HTML emails.

Email client HTML rendering is way more scattered than browser HTML. While you might have a pretty good understanding of what features and patterns you can use to support all major browsers, I doubt anyone masters this craft for HTML email clients.

The only way to ensure your email looks good (acceptable, at least) in all mail clients, is to check it. Litmus is your go-to solution for this (see below). While they actually offer a lot more, you can think of it as a "Browserstack for mail clients".

Best practices

  • Use tables for layouting. Use these HTML attributes: align="center", width="100%", valign="top"
  • Many mail clients do not support external style sheets. Some even require all styling inline, which means you'll have to do your styling inline. For Rails applications, you can use Roadie or premailer, which lets you keep your well-structured CSS files and do the inlining for you.
  • Provide a suitable alt text for images, and style it! Many email clients may refuse to load images for an unknown sender. Descriptive alt texts will help the user decide if they want to keep your email. Also, a simple styling will greatly improve the "no images" experience. Start with styling font-size, line-height and color on your images.


Even the most innocent change can break rendering for some devices. Known issues:

  • Some Android mail clients truncate horizontal padding and widths to make the email more readable in their eyes. However, this breaks sophisticated designs. You can fix this by adding an element with a definite width, e.g. a row of  . Since it cannot be wrapped, these mail clients will resize the email as a whole, keeping your designs intact.
  • Outlook will only respect image sizing when width and height are given as HTML attributes, not CSS, not even style attribute.
  • does not support margins. Create spacing by adding spare td elements with width or height attributes.
  • Thunderbird does not properly handle font color inheritance. In case a child element has an unexpected font color, set the color on that element explicitly.
  • iOS creates thin hair lines between adjacent table cells with a background color. Fix by wrapping the whole table in a single styled table cell.

Using Litmus

To validate an HTML email design, use Once you have an account, go to the builder projects page and create a new project. You'll be prompted to paste the email source.

In a second tab, open a preview of your designed HTML mail. It's best to take it from Staging, so that assets (images!) will be available to litmus during rendering. For a preview during develoment, you can also use your local Rails mailer previews. Take the preview HTML source and paste it to Litmus.

When the builder project is created, you'll see a split pane with HTML on the left and a preview on the right (which shows your browser's rendering). Follow "Run Email Previews" in the top right, then "Configure Email Clients" in the top left. Make sure you've selected a representative set of clients.

Now check the renderings of all clients. Since you've taken the HTML from staging, you can't easily generate an update preview by updating your code. Instead, modify the HTML in Litmus and port your changes to your code once it renders correctly.

Make sure to also check the mail in "no images mode", as some mail clients block images for unknown senders: open a mail client preview in Litmus and toggle images with the button in the top left.

Suggested clients

  • Recent Apple Mail
  • Recent IBM Notes
  • Recent Outlook + Windows Mail
  • Thunderbird
  • Recent Android + Google Inbox + Gmail App
  • iPhone 8, iPhone SE, iPhone X, iPad
  • Gmail (IE)
  • Select a few of the other web-based clients. Use IE, as it is the most likely to have rendering issues

Note that preview renderings are limited to 1000/month. With 15 Clients selected, each change to the HTML will trigger 15 renderings. When debugging a single client, you can deselect all others.

Dominik Schöler almost 3 years ago
This website uses short-lived cookies to improve usability.
Accept or learn more