Overview of email templating

Emails (or often referred to as transactional emails) are - just like the entire Magento theme - based on files in the filesystem: If you open up the folder app/locale/en_US/template/email you will numerous files. Don't edit them directly, because any Magento upgrade will override your changes. Instead, the purpose of these files is to override them.

You can override these email templates either using the Magento Admin Panel, or by copying them to your Magento theme. The first approach allows for easy editing using the Magento Admin Panel, but this interface lacks nice editing features like syntax highlighting or code completion. Ofcourse, you can copy the textarea contents ofcourse to your local editor modify things there and copy the code back into the textarea once you're done.

An alternative is to copy the email templates to your theming folder (app/design/frontend). This does not work out of the box with Magento, but there are various third party solutions out there that allow you to override email templates this way. (We offer you one solution for free.)

Either solution is fine. It is up to you to find out which approach you like best.

Modifying email templates in the Magento Admin Panel

In the Magento Admin Panel, email templates can be managed through System > Transactional Emails. The overview of email templates is empty by default, which means that all email templates are there on the filesystem but you have not created any override in the backend yet.

You can create a new override through the button Add New Template. In the new screen, select a template from the dropdown, change the locale if you want and hit the button Load Template. All code will then be copied from the filesystem to the Magento Admin Panel, so you can modify it at your will.

Each override also has a name, which used only internally. The subject and content end up in the mail that is actually sent to the customer.

Modifying email templates in the filesystem

Email templates are stored by default in the Magento filesystem in the folder app/locale/en_US/template/email and its subfolder sales. Do not modify these files. That would classify as a core hack and is unwise for numerous reasons. Unfortunately the Magento core does not allow you to create a theme override of these files. With our free extension Yireo EmailOverride you can bypass this problem.

Install the extension through your MagentoConnect manager or by uploading the patch-files, flush the Magento cache, and you are set to go. The EmailOverride extension allows you to copy files to your own themes locale folder. Here is one example, the first line being the original file, the second line being the theme override if your theme is called YOURTHEME:

app/locale/en_US/template/email/account_new.html
app/design/frontend/default/YOURTHEME/locale/en_US/template/email/account_new.html

Another example:

app/locale/en_US/template/email/sales/invoice_new.html
app/design/frontend/default/YOURTHEME/locale/en_US/template/email/sales/invoice_new.html

The cool thing of this approach is that you can also have different templates per Store View. The Magento backend approach does not allow for this. We use this approach personally, because it allows us to copy common email changes around between Magento sites on different servers.

Inspecting the code of email templates

In either case, you will end up with the code of the default email templates, which you can then edit to fit your needs. When looking at this code, you will discover HTML-code, CSS-code and some special code between brackets {{like this}} which Magento calls CMS tags. You should be able to find your way with HTML-code and CSS-code.

The CMS tags are more difficult - it requires programming skills to understand what is done here. Basically the tags are similar to PHP-code, as in that they refer to variables. Sometimes these variables are flat strings that can printed directly. For instance, your company logo (as configured in the Magento System Configuration) is printed like this:

{{var logo_url}}

But in some other cases, more complex structures are used. For instance, in order emails, the actual order is being reffered to as a variable object $order, and the CMS-tags allow you to call upon PHP-methods of that object. Here the customers full name is fetched using the getCustomerName() method:

{{htmlescape var=$order.getCustomerName()}}

To know which objects and which object methods can be used where, you'll have to debug which Magento class contains which functions - most likely by simply reading the Magento source code. Definitely a task for a Magento developer. Also, do not simply copy objects from one email to another. Every email has specific variables inserted into it. If you would copy the $order object to the contact email, this will result in a PHP Fatal Error, which again causes the email never to be sent.

Designing for multiple email clients

One of the harder parts of getting the design of email templates straight is that there are no standards for interpreting HTML-code in email clients: Every email client (Thunderbird, Outlook, Evolution, Postbox) uses its own HTML-rendering engine which might display your HTML code differently. The best approach to bypass these issues is to keep your emails basic and simple, and use old standards instead of new standards. For instance, HTML5 and CSS3 will only be partially supported, while HTML4 and CSS2 will work in almost all email clients. Most commonly you will add CSS properties to HTML elements using their style attribute.

Testing emails

When editing an email within the Magento Admin Panel, you can find a button Preview Template which opens up the mail in a new browser window. Unfortunately, this preview does not include actual data like invoice information or the actual products ordered. Also, this preview does not allow you to test the email under various email clients.

The usual way to test this, is to create a new order in the frontend (by adding products to the cart and completing the cart) so that an order email is being sent to a specific address. This procedure is very lengthy however. Also when you need to test the email layout under numerous email clients, you will need to create orders for each email address.

Our Yireo EmailTester extension definitely makes life easier: Within the Magento Admin Panel, you can visit the extensions control panel and use it to preview any email in your browser as you see fit. Real life data like order information and customer addresses are inserted on the fly. You can also quickly enter a specific email address to send the email to. This way you can send the same order email quickly to multiple email addresses.