Skip to content

Instantly share code, notes, and snippets.

@olliefwilliams
Last active October 13, 2021 11:10
Show Gist options
  • Save olliefwilliams/2fb119e8906f46b23583245558073d06 to your computer and use it in GitHub Desktop.
Save olliefwilliams/2fb119e8906f46b23583245558073d06 to your computer and use it in GitHub Desktop.

The Blackbridge guide to HTML emails

Table of contents

Introduction

Why does this need a guide?

HTML emails are deceptively complicated; there are a lot of moving parts and niggly details that are hidden to the recipients. There are so many variables and options, many of which go against common logic, that it is unreasonable to expect people to know how the whole process works simply by "figuring it out themselves", so this guide was created.

What this guide aims to do

The primary aim of the guide is to make the process of actually getting an HTML email "out the door" as smooth as possible. It is not intended to inform the reader of obscure technological information or to discuss the philosophy of why we send emails — it is a brief introduction into what an HTML email is, broadly how they "work", and what is needed to make one happen.

The process

There are quite a lot of individual steps and requirements for an average HTML email build. These are listed and explained in further detail below and are followed by a more general checklist that can be used as a "sense check" at the time of actual production.

This list (and indeed the whole guide) makes the assumption that we (i.e. Blackbridge) are not sending the email ourselves — it is the client who is actually delivering it to the recipient's inbox. This is an important bit of information because if we did send the email ourselves then this guide would be a lot longer!

It should also be noted that some of these steps can be skipped over, depending on the "familiarity" of the client. For example; if an email is part of a series that changes very little from one to the other, then it stands to reason that the Specifications and Design only really need to be looked at for the first of that series of emails.

1. Specifications

Before designing and building a new HTML email, it helps to know what mass mailing service the client is using and whether they have any specific requirements. These will not need to be answered for every email we produce, as we tend to work on series of newsletters, but typically we would like to know the answer to the following questions:

Do we need to host the images/will the client's system host the images?
If the client is using a more fully-featured mass mailing system, they may be able to upload the images and the HTML file in one go, and have their system completely manage all of the assets. This is preferable as it means that we are not "responsible" for hosting their images, and it makes development slightly quicker.

Do we need to inline the CSS?
Generally it's preferable for us not to do this as it's an extra step on our end, and most mass mailing services will have this functionality built in. Once an email is inlined, it makes editing it more difficult, so if the client has to add/edit any content on their end, we would typically not inline it.

Are there any merge tags that need to be included in the copy? A merge tag is a bit of text that is automatically replaced by unique, often personalised text for each individual email sent out by a mass mailing client. For example, an HTML email may open with the the text "Dear *|FNAME|*". The mass mailing service will automatically detect the *|FNAME|* merge tag and replace it with each individual recipient's actual name before it is sent to them. These are rarely seen or requested at Blackbridge, so this is not to be considered a critical question (though they are widespread enough in the field that they are worth mentioning in this guide).

2. Content

If we are not designing a broad, multi-use template, then the development team will need the text content to start the build. Please ensure that the content is approved, final and as clear as possible when handing it over to the development team.

Any links in the copy document should have their URLS next to them (or otherwise clearly labeled), and the phrase "click here" should not be used as this is seen as bad practice. Instead of using "click here", "read more" or similarly generic phrases, try to be more descriptive and let the user know where the link will actually take them. There are dozens of articles and blog posts written about this online: A brief guide written by Campaign monitor and another from MailPoet are good primers on this subject and offer examples of alternatives to use.

If there are any images that the client has specified need to be part of the email, whether that's photography, graphics or logos, then these will also need to be provided. Anything graphical should be a PNG file (transparent if it's a logo), and any photography should ideally be provided in the form of the original assets.

3. Design

Whilst this is the third step, it is quite possible to do this before the content is received (and certainly before it is properly finalised), provided a reasonably informative brief is supplied.

Designing an HTML email will usually have a reasonably quick turnaround, compared to designing other assets, as the design has to be kept quite simple to ensure that the final HTML file is compatible with all email clients. Here is a broad list of requirements/limitations:

  • The main body of the email should be approximately 600px wide.
  • Body copy font choice should be limited to certain certain web safe fonts. It is possible to use custom fonts, but they are not widely supported so a fallback font must be chosen. This will increase development and testing time and is generally not recommended.
  • No "live text" over an image. What this means is that it is impossible to set an image to be a background of a text block, for example. Any text placed over an image will have to be exported as a flat image with the text "baked in" This is usually seen as acceptable for header/hero images but not for other content.
  • It is not possible to put a form, a video or really anything other form of "rich media" in an HTML Email as they simply are not supported by a significant portion of clients. It is possible to use animated GIFs, but again, some clients will not load them properly, and will instead only show the first frame.
  • Complicated layouts should be avoided wherever possible. A single column design is the safest option as it greatly simplifies the build stage and thus reduces cost.

If the design is being done by someone outside of the build team, there are a few more requirements:

  • Design should be done in Sketch/Figma or Photoshop (or Illustrator, at a push). It should not be done in InDesign as this is for print work.
  • It should be considered that some assets will benefit from being exported at twice their display resolution, so as to look their best on retina/mobile screens.
  • The design should be approved as "buildable" by a developer before being shown to the client.

4. Build/Testing

Unlike the normal internet, there are dozens of programs that a user can (and does) use to read an email. Each one of these programs renders the code that makes up an email slightly differently, and some of these programs are wildly outdated or outright broken. This makes writing code that takes all of these (often directly conflicting) idiosyncrasies into account very challenging as well very time-consuming to test.

Due to these complexities, this stage can take a surprisingly long time and thus will take up a large proportion of the project budget. So it follows that all efforts should be made to ensure that no changes are made to the structure or design of the email once the build has commenced.

5. Delivery

The final deliverable will normally be a single HTML file but may also include a folder of the images used in the final design (e.g. the header image, any photos in the body of the email etc.) Whether or not this folder of images is necessary depends on the mailing system the client is using: some will automatically package and host the images themselves, others will need us to do it. Depending on the emailing service the client is using (that's the business client, not the email client) they may also need the file to be inlined so it's important to know whether this is a requirement or not.

Checklist

Before development can start, here is a brief checklist, which essentially condenses some of the information above:

  • Key specifications/requirements gathered
  • Copy approved
  • All links present in copy
  • Images approved (if applicable)
  • Design approved as feasible by development team (if not designed by them)

Glossary

Here are a few technical terms associated with HTML emails that it will be helpful to familiarise yourself with:

Mass mailing systems
You may have heard of or used these before; two of the most well-known ones are Mailchimp and Campaign monitor. These are both web-based options, but the client will likely be using something else that may tie in to their CRM system; SuccessFactors has one built in for example.

Whilst it's not gravely important, it helps to know what service the client is using as it means we can ensure that final deliverable files are tailored to their needs, should they need to be.

Campaign
The collective term for an HTML email or group of related HTML emails.

Client/Email client
In this case, a client is a bit of software that the recipient uses to actually receive and view the email. e.g. Apple Mail, Outlook Web, Outlook 2016, Gmail.

CSS
Stands for "cascading stylesheets". This is the code that defines the "style" of various elements that make up the content of the email — its colour, size, position and other properties.

Element
An individual "bit" of content. For example, a paragraph, heading, table, image, and a bulleted list can all be thought of as elements.

HTML
Stands for "hypertext markup language". This is the code that defines the sturcture or layout of the various elements that make up the content of the email. It's this that defines the order that the content comes in, and what separates each individual element from the next.

Inlining
Specifically, CSS Inlining. This is the act of taking all the CSS, which is typically kept out of the way at the top of the email, and putting it all right into the middle of the HTML code. This is done to ensure that the design is as unambiguous as possible and not "open to interpretation" by the receiving email client. Usually done right before sending the email.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment