Emails are actually their own HTML documents combined with some other metadata and attached files. Writing email markup is similar to writing HTML code for websites, but the process can be a bit tricky, as email clients are notoriously bad at rendering valid HTML, especially Microsoft Outlook.
To avoid some of the complexities, we have created our own email-templator utility to handle some of the concerns of writing emails so that they will render properly across many different types of email clients. The first sections of this page will outline how to use this, the following sections will deep dive into the particulars of best practices for writing HTML emails.
Using the Email-Templator
Our email-templator project is available as a consumable package and the code is available on Git:
- Npm Package to directly install and use.
- Github Project to view the source code.
To get started now: you can directly install via npm:
Let's start with an example of an HTML + CSS code we want to send as an email:
The HTML + CSS above is technically correct, but it may or may not render properly in certain email clients, as its use of css classes and id styling may not be interpreted properly.
Let's convert this into something that we can use with our email-templator:
We are now representing our CSS as a javascript dictionary object but are declaring it in a way which resembles CSS syntax. In the HTML, we are using {{#id|.class}} to denote where we want to indicate that styles should be applied.
If we put the pieces together, we will have the following:
Notice that we are interpolating css values as well as a separate values object. When passing in the CSS key-value object, the system will perform certain special actions depending on the input. When passing in the values object, the system will interpolate as is. The bottom of the input javascript code will accept the markup, styles, and values object (if any) and return the HTML.
In summary, to call the code to generate the markup:
Note on Security
This library does not offer any HTML sanitation. If you are inserting any dynamic markup / data which has not been cleansed, be sure to pass the data through some library before passing it in here.
Gudelines for Coding and Styling Emails
The email-templator will help streamline the process and avoid pitfalls common with writing emails, but there are other issues to consider when writing emails. This page will not provide an exhaustive list; the points below are a few examples of common pitfalls and points to consider:
When it comes to styling:
- Make styles inline, instead of creating classes separately, as much as possible. In some cases, email clients will not properly observe the css styles you've written if they are not inline.
- Do not refer to any external css, as the client will most likely not fetch that stylesheet.
- For width and height attributes, if you use them and assign px values, also create properties directly in the tag for width and height with the same numeric values.
- Avoid using flex, as email clients will most likely not render the layout properly. Consider using a table layout instead.
- For dyamically sized content, or sizings based on percentages, spend some extra time to validate they are working properly in email clients.
- Use standard, web-safe fonts, or the font may not render properly.
When it comes to HTML:
- Don't use form objects.
- Don't use iframe objects.
- Don't attempt to embed videos or other active media.
When it comes to Javascript:
- Don't.
- Email clients will not execute Javascript, ActiveX, Flash, or other types of scripting / active content.
Reusability on the Browser
One additional benefit of using this library: you can resue this tool to present the same content both on emails and on a website. On our website, we are taking advantage of this in a few separate places. By leveraging this, we are able to streamline the process of creating content and can better maintain that code, since we do not need to maintain it in two separate places or need two different implementations for the same presentation.