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.

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.

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.

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.

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.

<linkhref='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.

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.

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.

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.

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.

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.

Hello Francis,
as I wrote in the article, only the following clients support custom fonts: Outlook 2000, iOS Mail, Apple Mail, Android default eMail app, Mozilla Thunderbird. You can check the CSS Support Guide For Emails for additional reference on which clients support which features.

I would like insert available ‘QR’ from Sales_order table on New Order email template
The DB value of ‘QR’ is contain QR code image values as html format.
I append {{var order.qr_code}} on template to generate QR code image on email .
But it only display html content as text as can’t translate into html tag.

The information you collected and shared for transactional emails is really valuable. I added it to my list for further usage. Thank you for this.

For instance, it is good to remember 600px recommended width for all emails (I believe non-transactional as well).

In this article there is no information about responsive transactional emails. From your experience and testing, can we achieve support with same template for different devices?
I remember we played with it and there is no 100% way of having responsiveness.

Hello Max,
thank you for your reply. I am glad that you’ve found this article useful.

Regarding your question, I’ve actually never had a chance to work on a fully responsive Email. That could be because it’s really time consuming for a really small gain (since Apple iOS 7 and Apple Mail 6.5 and above support responsive concept, according to the Campaign monitor) or it’s too quirky to adjust it for those really few clients that actually support it and create a proper fallback. If you really want to tackle responsive emails, I would recommend searching through some of the many responsive Email templates available on the Web and see how to adjust them to work in Magento’s header and footer template. Feel free to let us know about your progress and what you discover.

Hi Max. I’m currently using responsive transactional e-mails in my stores. It’s all working very well. I pasted a (very stripped) template here http://pastebin.com/RKsVCqWs, so you can take a look at it and try it yourself. Good luck!

Your email address will not be published. Required fields are marked *

Comment *

You may use these HTML tags and attributes: <a href="" title=""> <blockquote cite=""> <code> <del datetime=""> <em> <s> <strike> <strong>. You may use following syntax for source code: <pre><code>$current = "Inchoo";</code></pre>.