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
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:
If we put the pieces together, we will have the following:
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:
- 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.
- Don't use form objects.
- Don't use iframe objects.
- Don't attempt to embed videos or other active media.
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.