Email template documentation
The jinja template can render emails with 1 of 4 different brands.
Note: 2. is effectively brand 1 + brand 3.
Email templates for services without an associated logo will use the first brand, GOV.UK, by default.
Each of the other brands require certain attributes for the template to render them successfully.
Note: the term 'government identity' refers to logos from the government identity system (PDF, 4.2MB).
The dimensions of logos vary. Their height will be set to either 27px, if the branding has text or 54px, if not. The width will adjust to keep the aspect-ratio (the default for HTML rendering). Note: the image resolution needs to be twice the size to look good on high resolution displays (so 54px for 27px or 108px for 54px).
When testing changes to the email template, it is important to be aware of all the possible variations because of the randomness of HTML rendering in some email clients and screen readers (ie. https://github.com/alphagov/notifications-utils/pull/1061).
| Brand type (from web page) | variation | brand_type database field | sections of template used |
|---|---|---|---|
| GOV.UK | N/A | null | section with if govuk_banner shows, no others do |
| GOV.UK and branding | branding below is logo without text | both | section with if govuk_banner shows along with section with if brand_logo and not brand_banner, brand_alt_text will be set |
| GOV.UK and branding | branding below is logo with text | both | section with if govuk_banner shows, along with section with if brand_logo and not brand_banner, brand_text will be set |
| GOV.UK and branding | branding below is government branding | both | section with if govuk_banner shows along with section with if brand_logo and not brand_banner, brand_text will be set and brand_colour will be the colour line next to the logo |
| Branding only | logo without text | org | section with if brand_logo and not brand_banner shows, brand_alt_text will be set |
| Branding only | logo with text | org | section with if brand_logo and not brand_banner shows, brand_text will be set |
| Branding only | government branding | org | section with if brand_logo and not brand_banner shows, brand_text will be set and brand_colour will be the colour line next to the logo |
| Branding banner | logo without text | org_banner | section with if brand_banner shows, `brand_alt_text will be set |
| Branding banner | logo with text | org_banner | section with if brand_banner shows, `brand_text will be set |
You can view the email template (with the current branding) at the /_email endpoint. So on production this would be:
https://www.notifications.service.gov.uk/_email
The following hacks have been added to make the template work with assistive technologies.
A common hack for HTML emails is to use blank images, set to a dimension to create empty space in your layout.
Because of the issue with alt text, any spacer images are announced to the user, which is not the intention. For this reason we should try not to use them.
Another common hack is to use space characters encoded as HTML entities (ie ), for empty
space in your layout. These are announced to users of screenreaders so should not be used. A
<br /> tag, which is not part of the content of the document, should be used instead.
HTML emails will be viewed on a large range of client programs and devices. The engine used to render the email can also change. Outlook, for example, has changed its renderer through the versions (see this history of outlook email rendering).
Because of this, our email template relies on hacks to let it display consistently across clients/devices.
Adding the following stops phone numbers being turned into links.
<meta content="telephone=no" name="format-detection" />
Clients will apply CSS depending on how it is defined but this is not consistent so multiple applications are needed.
CSS duplicated between the document head and inline styles.
<style type="text/css">
body { margin:0 !important; }
<body style="margin: 0">
Styles duplicated between inline CSS and HTML4-style attributes on the element.
<table
style="width: 100% !important;"
width="100%"
>
CSS used for layout is ignored by many clients. The pre-CSS method of using tables instead is currently the best way to build layouts that work across the greatest number of clients/devices. See this article on why use tables for layout in emails.
We give all our tables role="presentation" to ensure assistive technologies ignore them. We also zero their border, cell-padding and cell-spacing to ensure clients don't apply their own version of these values.
Microsoft-specific conditional comments can be used to deliver blocks of HTML only to certain versions of Outlook.
See this article on using outlook conditional comments for more detail.
<!--[if (gte mso 9)|(IE)]>
...
<![endif]-->
Clients can add their own CSS to emails. Using !important means the preceeding styles have a better chance of overwriting any CSS specific to that client.
Some clients strip CSS out from the head of the email. Using inline CSS ensures elements will still be styled if this happens.
The first line in the <body> of the template is used by clients to show a preview of the email (see the commit that adds the preheader for details.)
We use CSS to hide it from the email when viewed in full.
outlook.com strips margins out from CSS but capitalising them means it ignores them. This form is still recognised as valid CSS by all other clients. See this article on margins in outlook.com for details.
Support for the CSS property background-color across clients is buggy so we use the HTML4-style
bgcolor attribute instead. See this guide on support for
background-color.