Magento’s transactional eMails do-s and don’t-s

Editing and styling Magento’s transactional eMails and eMails in general can be a real headache. There are numerous reasons for that, for example the number of eMail clients available that have their own quirks and the complicated workflow of the testing process. This article will cover some of the general advices and tricks that will, hopefully, help you in development. These aren’t some general rules for the most part, but advices and guidelines that you may or may not use, which I discovered during my work on various projects.

Choosing the eMail clients for testing

Before you start working on your eMails, first thing that you should do is set up your testing environment. Usually, I choose around 9-12 eMail clients (alongside with a tool for local testing) to do the tests on, based on usage statistics from Litmus Labs. The way I see it, there are 3 general categories of eMail clients:

Default applications which come with the operating system or device (for example, default Android eMail app, default iPad eMail app, Windows 10 eMail app, etc.). These are most accessible applications for the users.
Web clients which are accessible from Internet browser (for example, Gmail, Outlook.com, Yahoo mail, etc.). These are second most accessible applications for the users.
Applications that require setup which may require purchase, download and installation (for example, Mozilla Thunderbird, Microsoft Office Outlook, Windows Live Mail, etc.).

This is also the priority I usually take when choosing eMail clients on which I do the tests. This way, we can cover most of the eMail clients and make sure that eMails display correctly across majority of devices and clients. Also, it is a good idea to take a look at the statistics of most used eMail clients before making decisions.

Defining the structure

When writing HTML and CSS for eMails, we have to use outdated and deprecated workflow and code, due to the lack of support in various clients. We cannot use HTML tags we would usually use today to define the layout; we have to resort to using tables for that. Magento also allows us to create custom header and footer HTML for the eMails that can be included and used across all Magento eMails. It is also important to consult and work with the designers to define the look and structure of the transactional eMails which can be fully supported by most, if not all eMail clients, without resorting to the fallback mechanism and eMail client hacks.

Look out for Outlook and Windows 10 Mail App

Microsoft Office Outlook and Windows 10 Mail App share the similar poor support of some HTML and CSS features. But luckily, there is a way to target those two particular eMail clients with the following simple lines of code.

If you want to add some specific CSS code for Outlook and Windows 10 Mail App, add your CSS between the style tag in Magento’s eMail Header.

<head>
	<!-- ... -->
	<!--[if mso]>
	<style type="text/css">
		/* CSS styles for Microsoft Office Outlook and Windows 10 Mail App */
	</style>
	<![endif]-->
</head>

If you want to show or hide HTML chunks of code for Outlook and Windows 10 Mail App (for example, if you want to inform the recipient to view the eMail in browser), add the HTML code between the following tags.

<!--[if gte mso 9]>
<!-- HTML code for Microsoft Office Outlook and Windows 10 Mail App -->
<![endif]-->

For reference, you can check out the official documentation for the CSS rendering capabilities for these eMail clients.

The problematic HTML paragraph <p> tag

The paragraph tag is one of the few block elements which are supported in eMails, but there are a few problems with it:

Outlook desktop application ignores any padding CSS applied to it
Outlook web client strips all margin CSS (without any exceptions) and replaces with their own custom bottom margins which cannot be avoided

Those are two specific reasons for me to avoid the paragraph tag. Any padding applied to the tag will only be ignored in outlook, but in outlook.com client the forced margins will just add more empty space along with the padding.

In Magento, the default eMail templates contain paragraph tags by default. The best solution I’ve found for this issue is to replace all paragraph tags with the following tags:

<span> <!-- Content of the block element --> </span><br/>

We only used inline span tag and line break tag to create our custom block element. This way we have a lot more control over it and we can be sure that there won’t be any forced styles applied to it. Using multiple line breaks before and after the block element you can control the vertical space between block elements. This may not be the best solution, but it did make the eMails look consistent across all eMail clients and it gave me a proper control over the vertical spacing.

Issues with <ul> and <ol> tags

One of the (many) common issues with Outlook and Windows 10 Mail App eMail rendering is bug in rendering bullets in list elements. This issue causes list bullets not being displayed in eMail. There are two ways of fixing this issue – by using CSS (more universal across the eMails) and by using HTML (requires changing code and layout for each instance of list elements).

CSS solution consists of applying left margin to the <ul> and <ol> elements in your eMails. To prevent really large left margins on other eMail clients, combine this CSS code with Outlook targeting code.

<head>
	<!-- ... -->
	<!--[if mso]>
	<style type="text/css">
		ul{
		margin:0 0 0 50px; /* Horizontal margins only */
		}
		li{
		margin:0 0 12px 0; /* Vertical margins only */
		}
	</style>
	<![endif]-->
</head>

Another solution is to replace your <ul> and <ol> tags with tables and use UNICODE bullet point characters (like “•”) to represent lists.

<table width="100%" border="0" cellspacing="0" cellpadding="0">
	<tr>
		<td valign="top">&bull;</td>
		<td valign="top">Text</td>
	</tr>
	<tr>
		<td valign="top">&bull;</td>
		<td valign="top">Text</td>
	</tr>
	<tr>
		<td valign="top">&bull;</td>
		<td valign="top">Text</td>
	</tr>
</table>

Web fonts and proper font fallback

Web fonts are supported by only some eMail clients, which makes the proper font fallback very important if you don’t want to see a default eMail client font in your eMails. Web fonts are supported by the following eMail clients:

Outlook 2000
iOS Mail
Apple Mail
Android default eMail app
Mozilla Thunderbird

Even if you provide a proper fallback, like you would when you’re writing CSS for websites, Outlook and Windows 10 Mail app (surprise, surprise) can cause issues by not respecting the fallback if the web font is used. In case of Web font, Outlook and Windows 10 Mail app set their font to “Times New Roman” or other default font without respecting the provided fallback. To avoid trouble with Outlook and Windows 10 Mail app, create a standard font fallback wrapped in tags that only target those eMail clients.

Add the following line in the Magento’s Header template.

<link href='url-to-external-font' type='text/css'>

Add the following code to Magento’s noninline eMail CSS file or to the CSS text input in Magento’s eMail editor.

@import url(url-to-external-font);
	@media screen {
		body,
		td {
			font-family: "External font", fallback-fonts !important;
		}
}

And add a special font fallback code in Magento’s Header template for Outlook and Windows 10 Mail app (we know for sure that external fonts aren’t supported):

<head>
	<!-- ... -->
	<!--[if mso]>
	<style type="text/css">
		body, table, td, span, a, b {
		font-family: fallback-fonts !important;
		}
	</style>
	<![endif]-->
</head>

Bulletproof background images and buttons

Adding Image backgrounds and buttons to Magento transactional eMails and Newsletters can certainly make your eMail stand out and make it interesting and engaging to the users, but background image support and buttons support is very poor on some browsers like Outlook (both web and desktop clients) and Windows 10 where it’s difficult to set a background image and even then, it is limited to a single image.

Luckily, there are a few great online tools that will help you create, preview and edit your container with background image and buttons with universal support.

Campaign monitor’s bulletproof backgrounds generator

Campaign monitor’s bulletproof buttons generator

While creating container with background image for Magento eMails using these online generators, remember to change the image links to your media folders after you added the generated code to your Magento image.

Hiding content in eMail

Even simple styles like hiding content in eMail can be difficult due to the poor support of the “display” CSS. But luckily, there is a bulletproof method that ensures that content remains hidden in eMail method. Some of the code relies of setting the height and width of the element 0 and hiding the overflow, and some of the code relies on using Microsoft Office style “mso-hide” to hide the element on Microsoft’s eMail clients.

.hidden {
	display: none !important;
	mso-hide: all !important;
	overflow: hidden;
	line-height: 0px;
	font-size: 0px;
	width: 0px;
	height: 0px;
	margin-top: 0;
	margin-bottom: 0;
	margin-right: 0;
	margin-left: 0;
	padding-top: 0;
	padding-bottom: 0;
	padding-right: 0;
	padding-left: 0;
}

Adjusting maximum width and centering eMail in client window

Similar to the previous section of this article, even adding maximum width and centering the eMail layout can be a real headache, but with the following code and following default Magento eMail structure, you can center the fixed-width table. It’s also important to note that eMail width shouldn’t be wider than 600px, this is a general rule and most frequent advice I got. Use the following HTML attributes in your Magento Header template on table and table cell tags to add the maximum width and center the eMail.

<table align="center" cellpadding="0" cellspacing="0" border="0" width="600" style="max-width:600px; width=600px;">
<tr>
	<td align="center" width="600" style="max-width:600px; width=600px;">
		<!-- ... -->

List of widely supported CSS attributes

Best way to avoid additional fixes and special fallback code is to check out and try to memorize the CSS attributes which are widely supported and plan for various fallbacks if there is a required, but not widely supported, CSS attribute which must be used in eMail CSS. Based on the current list on Campaign Monitor’s website, the widely supported CSS attributes are:

Text & Fonts
direction	font	font-family
font-style	font-variant	font-size
font-weight	letter-spacing	line-height (except on <td> element)
text-align	text-decoration	text-indent
text-transform	vertical-align
Color & Background
color	background (limited support for images)	background-color
HSL colors
Box model
border	padding (not supported for <p>, <div> and <a> )	width (not supported for <p> and <div>)
Lists & Tables
list-style-type	border-collapse	table-layout

Taking a peek into transactional eMails in Magento 2

Transactional eMails editor in Magento 2 isn’t any different from transactional eMails editor in Magento 1.9, apart from the new, modern look. It has the same barebones text input for HTML structure and CSS. The default templates have been changed, like the eMail Header which now has added meta tags for modern browsers like Microsoft Edge and automatically adds <style> tag in <head> for noninline CSS, or the new email.css in Magento 2 to be more specific.

Magento 1 Default eMail Header

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html >
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <meta name="viewport" content="initial-scale=1.0, width=device-width" />
</head>
<body>
{{var non_inline_styles}}
<!-- Begin wrapper table -->
<table width="100%" cellpadding="0" cellspacing="0" border="0" id="background-table">
    <tr>
        <td valign="top" class="container-td" align="center">
            <table cellpadding="0" cellspacing="0" border="0" align="center" class="container-table">
                <tr>
                    <td>
                        <table cellpadding="0" cellspacing="0" border="0" class="logo-container">
                            <tr>
                                <td class="logo">
                                    <a href="{{store url=""}}">
                                        <img
                                            {{if logo_width}}
                                            width="{{var logo_width}}"
                                            {{else}}
                                            width="120"
                                            {{/if}}
 
                                            {{if logo_height}}
                                            height="{{var logo_height}}"
                                            {{else}}
                                            height="67"
                                            {{/if}}
 
                                            src="{{var logo_url}}"
                                            alt="{{var logo_alt}}"
                                            border="0"/>
                                    </a>
                                </td>
                            </tr>
                        </table>
                    </td>
                </tr>
                <tr>
                    <td valign="top" class="top-content">
                    <!-- Begin Content -->

Magento 2 Default eMail Header

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html >
	<head>
		<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
		<meta name="viewport" content="initial-scale=1.0, width=device-width" />
		<meta http-equiv="X-UA-Compatible" content="IE=edge" />
		<style type="text/css">
			{{var template_styles|raw}}
			{{css file="css/email.css"}}
		</style>
	</head>
	<body>
		{{inlinecss file="css/email-inline.css"}}
		<!-- Begin wrapper table -->
		<table class="wrapper" width="100%">
		<tr>
			<td class="wrapper-inner" align="center">
				<table class="main" align="center">
		<tr>
			<td class="header">
				<a class="logo" href="{{store url=""}}">
				<img
				{{if logo_width}}
				width="{{var logo_width}}"
				{{else}}
				width="180"
				{{/if}}
				{{if logo_height}}
				height="{{var logo_height}}"
				{{else}}
				height="52"
				{{/if}}
				src="{{var logo_url}}"
				alt="{{var logo_alt}}"
				border="0"
				/>
				</a>
			</td>
		</tr>
		<tr>
			<td class="main-content">
				<!-- Begin Content -->

Final steps

After you finish editing, styling and testing Magento’s transactional eMails, it’s a good idea to do an overall test and final check on all eMail clients at the same time and compare the results just in case to see if there are any minor issues with styles and layout that you might have missed.

After that, you can do a spam test. Spam test determines the chance of your eMail being caught in a spam filter by analyzing the contents of the eMail (like Subject of the eMail and plain text) and eMail code. There are many free online tools which can be used for spam testing. Even though spam analyzers cannot ensure that your email won’t be stuck in every existing spam filter due to their quirkiness, they can help you minimize the chances of that happening by ensuring that your eMail is up to standards.

These have been all the helpful little tricks that I have learned over the few months of working on transactional eMails and I hope that they will help you out too. If you have any more helpful and cool little tricks and code snippets for eMails, feel free to add your comment below this article.