Magento Email Templates: Complete Guide

Transactional emails are the primary communication channel used to notify customers about their orders, shipments, refunds, and other details. How you structure and configure them defines how effective they will be.

Luckily, Magento already has all the tools you need to customise default email templates and offers some custom variables to personalise them.

In this guide, you'll learn everything about Magento email templates. From customising the default template to creating a new one from scratch we'll cover every detail to help you successed in your Magento marketing efforts.

What Are Magento Email Templates?

Magento email templates are pre-designed HTML and text layouts you use to send automated emails to your customers. These templates cover different types of customer-store interactions.

There are different types of Magento email templates:

• Sales email templates (new order, order update, invoice, shipment, credit memo) are used to inform customers about their order status.
• Customer email templates (new account, password reset, email confirmation, account update, welcome email) are used to send customers account-related messages.
• Newsletter email templates (subscription success, unsubscription success, confirmation request) are sent during newsletter subscription and so on.

To find the full list of Magento default templates, go to Marketing > Communications > Email Templates > Add New Template > Load Default Template and select the Template option.

Each default email template consists of a header, body, and footer to match standard email formats.

• Header: the top section of every email. It contains a logo, brand name, design, and styling. This is the perfect place to help your customers identify your company at first glance.
• Body: the main part of an email that delivers the key message and varies depending on the purpose of your email. It contains clear and engaging content that encourages customers to take action.
• Footer: the bottom section of your email that wraps things up. It may provide contact details, social media links, unsubscribe options, and so on.

These templates are built using HTML and CSS, offering easy customisation and editing.

However, if you want to modify a default template, you need to create a custom version following all the layout rules.

Magento 2 Email Template Layout Rules

Whether you choose to create or edit Magento 2 email settings, it's important to follow certain layout rules. It is required so that your emails are displayed correctly across different email clients and devices.

Here are the key rules you should take into consideration when working with Magento transactional emails:

• Use table-based layouts: when structuring your layout, use <table> instead of <div>, as modern email clients (Gmail, Outlook, Apple Mail) don't support modern HTML and CSS completely. Instead, they support table-based layouts, which have been the gold standard in email design for years.
• Stick to HTML 4 standards, as many email clients do not support HTML 5 fully. Some of the tags can break the layout or be ignored completely.
• Use HTML attributes instead of CSS where possible: it will help your email to display well even in outdated email apps.
• Use inline CSS styles: some email clients ignore CSS in <style> tags. However, using inline styles ensures your emails look correctly everywhere.
• Use only CSS2 properties: drop shadows, animations, and all the other CSS3 effects can break your design. So stick to basic CSS2 properties to reach better compatibility.
• Use specific CSS properties: use "background-color" instead of "background", and write "padding-top", "padding-left", etc., instead of shorthand.
• Don't use short hex color codes: it means that instead of #FFF, use #FFFFFF, as some email clients only support a full 6-digit version of the color name.
• Avoid background images: many email clients tend to block background images or don't support them.
• Don't use JavaScript in email templates: it is blocked by email clients for security reasons.
• Optimize images before sending: compress and resize images before adding them to your email, as it reduces the chances of triggering spam filters.
• Keep email width around 600 pixels: this is the size that works best on most screens, reducing the need to scroll sideways.

Email communication is very important in any e-commerce store, regardless if it's order confirmation, shipping updates, or reset password emails.

Following the layout rules will help you make sure each message is rendered and displayed properly. However, structuring the content within those emails is an entirely different thing.

So next, you need to learn how to edit, customize, and create Magento email templates.

How to Customise Email Templates in Magento?

You already know, Magento comes with a range of default templates that can cover all sorts of messages. So all you need to do is basically adjust the ready-made templates to meet your specific email strategy.

Check out this short video on how to edit email templates in Magento 2, or follow the instructions we share below.

Step 1. Load the template

First, you need to load a template. To do so, go to Marketing > Communications > Email Templates and choose an email template you want to edit. If you want to create a new one from scratch, hit the Add New Template button.

When creating a new template, just choose one of the drafts from Templates and press the Load Template button.

Step 2. Edit the template information

Next set the Template Name and change the Template Subject if needed.

Finally, edit the Content of the template and add the Template Styles, if necessary.

Once you finish, Preview the template to double-check the layout before saving. Then make sure to Save the Template afterwards.

Step 3. Assign email template in the configuration

You might have noticed the Currently Used For info when loading the email template. It tells you exactly what the default templates are used for. e.g. email confirmation, etc.

So, as soon as you create a new template, you have to assign it to a specific config section.

We've created our template based on the default New Order Template. So we go to Stores > Settings > Configuration > Sales > Sales Emails to apply our new template.

Step 4. Add email logo

Finally, once you've created the email template and assigned it to the store configurations, you need to customise the email logo.

To do this, go to Content > Design > Configuration and choose the corresponding scope to Edit the email logo. It's best to do that globally.

Scroll down to the Transactional Emails section and fill out the following fields:

• Logo Image: upload the primary branding element image in .png, .jpg, or .gif formats to be added to your Magento email templates.
• Logo Image Alt: set alternative text for the image. It will appear when your logo is not rendered for some reason.

• Logo Width and Height: specify the width of your logo. If you don't set anything, the image will appear at the original dimensions and break your email layout.
• Header Template: choose the header template you have customised, otherwise, Magento will use the default one.
• Footer Template: define the customised footer to be used in your emails instead of the default one.

Don't forget to Save the settings when you finish.

How to Customise Magento Email Templates Programmatically?

Editing Magento email templates in the admin is a simple way to change texts, update brand identifiers, and add any personalised "touches". However, sometimes you need to include custom blocks or complex logic in your template.

That's when the admin template editor isn't going to suffice. You need to do it the other way.

All Magento email templates are kept in the codebase under the "view" location:

vendor/module-name/view/frontend/email/

or custom themes/modules, you might have created:

app/design/frontend/Vendor/theme/Magento_Module/email/

In this case, you can override the default templates by putting customised .html files in a corresponding module or theme path.

Let's customise the Order Confirmation Email Template as an example, but use code this time.

To override this template, copy the default template from:

vendor/magento/module-sales/view/frontend/email/order_new.html

and paste it into your theme:

app/design/frontend/Vendor/theme/Magento_Sales/email/order_new.html

Then customise the HTML, layout, and variables the way you need, and run the following commands:

php bin/magento setup:static-content:deploy
php bin/magento cache:clean

Don't forget to flush the cache once you finish.

But what if you want to create a brand-new email template rather than customising the default ones?

Create an Email Template in Magento From Scratch

If your store has unique branding or multiple store views and you need to create new templates to meet specific requirements, take the following steps:

Step 1. Navigate to your custom module

Go to the module folder where you want to locate a new template. If your store name is, let's say, "Magefan", then your module name will be Magefan_EmailTemplate. In this case, the module directory will look like this:

app/code/Magefan/EmailTemplate/

Step 2. Create the email_templates.xml file

This file will contain your Magento email template configurations under:

app/code/Magefan/EmailTemplate/etc/email_template.xml

Step 3. Add template configurations:

It will tell Magento where to find and how to register the template you want to create. The content of the file can be as follows:

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Email:etc/email_templates.xsd">
       
    <template id="magefan_custom_email_template"
              label="Magefan Custom Email Template"
              file="magefan_custom_email_template.html"
              type="html"
              module="Magefan_EmailTemplate"
              area="frontend"/>
</config>

Here,

• id: is a unique name of this template
• label: human-readable label visible in the template dropdown
• file: is the path to your template file
• type: tells the format of the email, whether it's text or HTML
• module: the name of your module
• area: specifies the area where the email will be used

Step 4. Create the email template file

Create your template file under the following path:

app/code/Magefan/EmailTemplate/view/frontend/email/magefan_custom_email_template.html

Here is an example of its content:

<!-- Email Header -->
<p>Hello {{var customer.name}},</p>

<p>Welcome to our store! This is a custom email from Magefan's Module.</p>

<p>Order ID: {{var order.increment_id}}</p>

<!-- Email Footer -->
<p>Thank you,<br/>The Magefan Team</p>

Custom Magento email templates are the best place to use dynamic data. That is variables and directives that bring some automation to your emails.

Directives and Variables in Magento Email Templates

Dynamic data in Magento emails is information that changes or updates depending on the email you send using a templating system with directives and variables.

In simple words, dynamic data helps to change some parts of an email dynamically to personalise it for different customers or groups.

This feature is generally realised through directives and variables, in double curly braces, used in transactional emails. They help you to specify the customer's name, order number, and billing address, etc:

Hello {{var customer.name}}, your order number is {{var order.increment_id}}.

Using these directives and variables allows Magento to place unique information in each email, depending on what you want to send: image, link, or text.

The main types of email template directives are: store URL directives, variable directives, translation directives, and media directives. Let's see what each one does.

Store directive

The store directive automatically puts a link to the homepage if you leave the URL value in the template empty:

Visit our store: <a href="{ {store url=''} }">Click here</a>

If you need to, you can insert a link to any other page of your store, you should follow this practice:

<a href="{ {store url='category-url-key'} }">Category</a>

<a href="{{ var this.getUrl($store, 'customer/account/')}}">My Account</a>

<a href="{{ var this.getUrl ($store, 'customer/account/login')}}">Login</a>

Variable directive

The variable (or var) directive is used to insert values like the customer's name, order ID, date of the purchase, etc.

So, for example, if you have the following dynamic variables in your template

Hello {{var customer.name}},  
Thank you for your order #{{var order.increment_id}} placed on {{var order.created_at}}.

they will automatically render in your email as:

Hello John Brown, 
Thank you for your order #000004321 placed on 2025-06-02.

There is a complete list of Magento email variables you can choose from.

Translation directive

The translation (or trans) directive adds text to the email that can be translated into different languages depending on the store view locale settings.

If Magento detects the trans directive in the email template, it looks for a corresponding translation in the available CSV files or language packs. So, for example, if your template has the following trans directive

{{trans "Thank you for your purchase!"}}

the French store view will automatically change it into (in case you have a French language pack installed)

Merci pour votre achat!

However, if Magento can't find the translation, the default message will remain in the original language.

Media directive

The media directive is used in Magento email templates to generate the URL to the logo, banner, or image stored in your media directory.

Magento will extract the needed path to the corresponding file from your media folder.

So, if your template holds the following media directive:

<img src="{{media url='logo/logo.png'}}" alt="Store Logo">

Magento will convert it into something like:

<img src="https://yourstore.com/pub/media/wysiwyg/logo.png" alt="Store Logo">

Common Email Template Issues

Although Magento enables you to easily create dynamic and personalised email templates for your needs, there are still some issues you should be aware of.

1. Email template won't save

Sometimes, when trying to save a customised email template in Magento, you may get a "Something went wrong while saving the template" notice. There can be a few reasons for this:

• Invalid template syntax: make sure HTML or variable syntax is correct.
• Required fields are missing: if you leave any of the required fields empty, an error will occur.
• Permission issues: certain user role may not have permission to change and save templates.
• Admin session timeout: Magento may fail to save the template without showing an error if your admin session has timed out. To resolve this, log back in and try to save it again.
• Cache or compilation problems: clear the cache via System > Cache Management or run the following CLI commands:

bin/magento cache:clean
bin/magento cache:flush

2. Transactional emails failing to send

If a transactional email fails to send, try sending a default template. If the problem is with the customised email template, only reset it to the default one and apply changes gradually.

3. Template variables not showing

If Mageno fails to show email template variables, make sure you are using the correct var syntax and not missing anything. Sometimes, a small mistake or wrong spelling in variables can cause errors.

If the error persists after correction, go to System > Cache Management and flush the cache.

4. Missing email logo

If your email logo is not showing, first verify its path and directive. Then, make sure you've set your email logo globally and made it inheritable on all store views.

For that, go to Content > Design > Configuration, choose the scope where you have logo issues, and scroll down to the Header section. Make sure the Use Default box is ticked.

You may also need to clear the cache.

5. Layout or design display issues

As you may already know, various email clients can render your customised emails differently. It's a well-known challenge when it comes to customising email templates.

So, to be on the safe side, read the email template layout rules before customising emails.

Achieve More Email Templates in Magento

Email communication is crucial at every stage of the customer's journey. It builds trust, improves brand recognition, and helps you to offer your customers a better service.

Magento assists you with that by offering multiple default templates and extensive customisation options.

However, it might not be sufficient for more advanced strategies. If you want to segment your customers to send review reminders, abandoned cart and other emails, you need more sophisticated tools like Mautic Integration.