
To customize a Magento 2 transactional email, copy the core template, such as order_new.html, into your theme under Magento_Sales/email, or create a template in the Admin under Marketing, Email Templates and assign it in Stores, Configuration. Admin templates win over theme files. Since 2.4, templates must use strict-mode variables, and order emails can be sent asynchronously by cron.
Transactional emails are the most read pages your store sends, and they are some of the easiest to break. A template copied from an old blog post calls an object method that strict mode no longer resolves. An Admin template overrides a carefully built theme file and nobody remembers it exists. Async sending is switched on, cron stalls, and order confirmations stop without a single error on the storefront. This guide covers how email templates are found, how to override them, what variables and directives are allowed, and how asynchronous sending works on Magento and Adobe Commerce.
Where Magento finds an email template
Every transactional email is declared in a module’s etc/email_templates.xml. The Sales module, for example, declares the new order email like this:
<template id="sales_email_order_template" label="New Order" file="order_new.html"
type="html" module="Magento_Sales" area="frontend"/>
The id matches a configuration path, the file is the HTML template, and area decides which theme fallback applies. Default files live in <module_dir>/view/<area>/email.
When Magento sends that email, it resolves the template in this order, from highest priority to lowest:
- A template created in the Admin and assigned to that email in configuration
- A theme override at
<theme_dir>/Magento_Sales/email/order_new.html - Parent theme overrides, through normal theme fallback
- The module default in
view/frontend/email
Adobe’s email templates guide states directly that templates created in the Admin take precedence over default and theme-based templates. That single rule explains most “my theme change does nothing” tickets.
| Method | Where it lives | Version controlled | Per store view | Best for |
|---|---|---|---|---|
| Theme override | app/design/frontend/Vendor/theme/Magento_Sales/email/ |
Yes | Through theme assignment | Developer-owned layout and structure |
| Admin template | Database, Marketing, Communications, Email Templates | No | Yes, assigned per scope | Copy changes by store teams, one-off campaigns |
| Module default | vendor/magento/module-sales/view/frontend/email/ |
Composer | No | Never edit directly |
Overriding a template in your theme
Copy the default file into your theme, keeping the module folder name:
vendor/magento/module-sales/view/frontend/email/order_new.html
-> app/design/frontend/Vendor/theme/Magento_Sales/email/order_new.html
Edit the copy, then clean caches. In production mode, deploy static content so the theme’s compiled email styles are rebuilt.
The same pattern applies to the shared header and footer. Every frontend template pulls them in with:
{{template config_path="design/email/header_template"}}
{{template config_path="design/email/footer_template"}}
The defaults are header.html and footer.html in Magento_Email/view/frontend/email. Override them in <theme_dir>/Magento_Email/email/. Changing the header once updates every email, which is usually what brand teams actually want.
The email logo has its own route. Either set Logo Image, Logo Width, and Logo Height under Content, Design, Configuration, or add logo_email.png to your theme’s Magento_Email/web folder. Adobe recommends uploading at three times the display size so it stays sharp on high-density screens.
Keep overrides small. Every copied template is a file you must compare against core on each upgrade. If you only need different wording, an Admin template or a translation entry is less maintenance than a full theme copy.
Overriding a template in the Admin
Go to Marketing, Communications, Email Templates, and choose Add New Template. Load the default template you want to change, edit it, and save. The template does nothing yet. Note the “Currently Used For” path, then assign it in Stores, Configuration, Sales, Sales Emails, under the matching section and scope.
Admin templates have one strong advantage: different store views can use different templates without a code deploy. They have two weaknesses: they live in one environment’s database, and they are easy to forget. Before a template redesign, list every Admin template and check which ones are assigned. Otherwise a redesigned theme file can sit behind an old database template for months.
Template variables and strict mode
Emails get their data from variables passed by the sending code. The top of each template declares the available variables in a @vars comment, which also feeds the Insert Variable button in the Admin. The current order_new.html in core includes entries such as order.increment_id, order_data.customer_name, store.frontend_name, store_email, and formattedBillingAddress|raw.
The rule that changed everything is strict mode. According to Adobe’s email template migration guide:
- From 2.3.4, new custom templates could use only scalar values for variable data.
- From 2.4.0, the template filter uses strict mode by default.
- From 2.4.4 and 2.4.3-p2, the legacy variable resolver classes were removed, so legacy templates in the database resolve only in strict mode.
In practice, strict mode means a var directive can no longer call arbitrary object methods.
| Legacy syntax | Strict-mode syntax | Notes |
|---|---|---|
{{var order.getEmailCustomerNote()}} |
{{var order_data.email_customer_note}} |
Method calls are not resolved |
{{var subscriber.getConfirmationLink()}} |
{{var subscriber_data.confirmation_link}} |
Sending code must pass the value |
{{var order.getCustomerName()}} |
{{var order_data.customer_name}} |
Core senders already populate order_data |
{{ var order.increment_id }} |
{{var order.increment_id}} |
No spaces inside the braces |
Objects that extend DataObject can still be read with getter-style syntax, but Magento calls getData() with the matching key rather than running the getter. getUrl calls such as {{var this.getUrl(...)}} continue to work. When you need a computed value that is not in the variables, add it in the sending code, or write a custom directive that implements ProcessorInterface and register it in di.xml under the processor pool.
Two commands check existing templates for legacy syntax:
bin/magento dev:email:override-compatibility-check
bin/magento dev:email:newsletter-compatibility-check
The first scans Admin email templates in the database. The second scans newsletter templates. For overrides in a theme, Adobe points to the Upgrade Compatibility Tool. Run these before any upgrade that crosses 2.4.4. A template that fails to resolve a variable often renders an empty value rather than throwing an error, so the only symptom is a blank line in a customer’s inbox.
The directives you will actually use
| Directive | Example | What it does |
|---|---|---|
var |
{{var order.increment_id}} |
Prints a variable. Filters like escape, nl2br, and raw can be chained |
trans |
{{trans "Thank you for your order from %store_name." store_name=$store.frontend_name}} |
Translatable text with named placeholders |
depend |
{{depend store_phone}}...{{/depend}} |
Renders the block only if the value is not empty |
if |
{{if logo_width}}...{{else}}...{{/if}} |
Conditional with an optional else branch |
template |
{{template config_path="design/email/header_template"}} |
Includes another template |
layout |
{{layout handle="sales_email_order_items" order=$order area="frontend"}} |
Renders a layout handle, used for the items grid |
config |
{{config path="general/store_information/hours"}} |
Reads a system configuration value |
inlinecss |
{{inlinecss file="css/email-inline.css"}} |
Inlines CSS into elements |
css |
{{css file="css/email.css"}} |
Outputs non-inline CSS in a style tag |
A few details from core templates are worth copying:
- The subject line is defined in a comment at the top of the file:
<!--@subject {{trans "Your %store_name order confirmation" store_name=$store.frontend_name}} @-->. - Named placeholders in
transmust not have spaces around=. Adobe’s guide also notes that values containing spaces need brackets. - HTML inside a translation needs the
|rawfilter, as core does for links:{{trans '... <a href="%account_url">...</a>' account_url=$this.getUrl(...) |raw}}. transphrases use the store’s locale dictionary. Email strings are translated through the same CSV files as the storefront, so add them to your theme’s locale CSV rather than hardcoding a second language into the template.
Styling emails on a Hyva storefront
Hyva replaces the storefront’s LESS and RequireJS stack with Tailwind CSS and Alpine.js, but Magento’s email pipeline still expects LESS. The inlinecss and css directives compile email-inline.less and email.less from the theme fallback chain. Hyva’s documentation covers a preparation step that copies the required email LESS files into a Hyva theme, and an optional approach on styling emails with Tailwind that compiles Tailwind @apply rules into a LESS file. The documented steps target Hyva 1.3.x with Tailwind v3, and the page notes that Hyva 1.4 and newer need configuration changes and that Tailwind 4 has no good email solution yet.
The practical takeaway: plan email styling as its own task in a Hyva theme build. It does not come along automatically when the storefront moves to Tailwind.
How asynchronous email sending works
By default, Magento sends the order confirmation during the request that places the order. If the mail server is slow, the customer waits. Asynchronous sending moves that work to cron.
Turn it on under Stores, Configuration, Sales, Sales Emails, General Settings, Asynchronous sending. The relevant configuration from the Sales module’s config.xml:
| Setting | Config path | Core default |
|---|---|---|
| Asynchronous sending | sales_email/general/async_sending |
0 (disabled) |
| Limit per cron run | sales_email/general/sending_limit |
50 |
| Send attempts | sales_email/general/async_sending_attempts |
3 |
When async sending is on, placing an order marks the entity as needing an email instead of sending it. Four cron jobs in the default group then pick up pending entities, each scheduled to run every minute in core crontab.xml:
sales_send_order_emailssales_send_order_invoice_emailssales_send_order_shipment_emailssales_send_order_creditmemo_emails
Each run selects entities flagged with send_email = 1 whose email_sent value shows they are still pending, sends up to the configured limit, and updates the flag. The “Limit per cron run” field only appears in the Admin when async sending is enabled.
Three consequences follow directly from this design:
- Cron is now in the critical path. If the
defaultcron group stops running, order confirmations stop. Nothing fails at checkout. Our guide to Magento 2 cron groups and the cron_schedule backlog explains how to see whether jobs are running, missed, or stuck. - The limit caps throughput. With the default of 50 per run and one run per minute, a flash sale that takes several hundred orders in a few minutes builds a queue. Raise the limit if your mail transport can handle it, and watch the backlog during peaks.
- Concurrent workers can collide. Adobe has published quality patch ACP2E-5059 for duplicate order confirmations when two sales email cron jobs process the same order at the same time. If customers report getting two confirmations, check whether your version needs it.
To test async sending on a staging server, enable it, place an order, then run bin/magento cron:run. You may need to run it twice the first time, so the job is scheduled before it executes. A second run should not resend the same email.
Synchronous vs asynchronous: which to choose
| Factor | Synchronous (default) | Asynchronous |
|---|---|---|
| Checkout response time | Includes mail send time | Not affected by mail |
| Depends on cron | No | Yes, the default group |
| Failure visibility | Errors surface in the request and logs | Silent if cron stops |
| Peak order volume | Each request pays the cost | Queue builds, drained per cron run |
| Duplicate risk | Low | Possible with concurrent workers on unpatched versions |
Async sending is the better default for stores with meaningful volume or an external mail service that is sometimes slow. It is only safe if cron is monitored. If nobody watches cron_schedule, synchronous sending at least fails loudly.
Template work and sending mechanics are only half of email. Whether a message reaches the inbox depends on authentication and reputation, which we cover in transactional email deliverability for Magento. For a wider view of cron and indexer problems that make stores feel slow, see Adobe Commerce cron and indexer health.
A checklist before you ship email changes
- List Admin email templates and confirm which are assigned at each scope.
- Keep theme overrides to the templates you truly need, and note the core version you copied from.
- Run the two compatibility check commands and fix any method calls in
vardirectives. - Add every new
transphrase to each locale’s CSV. - Send real test orders for each store view and check the subject, logo, items grid, and footer.
- If async sending is on, confirm the four sales email cron jobs are succeeding and the backlog is empty.
The same discipline carries to other platforms. Stores on Shopify, Shopware, or BigCommerce use different template languages but face the same questions about who owns templates, how they are versioned, and how sending is monitored. You can learn more about Bemeir, see our technology partners, or start at the Bemeir home page.
FAQ
Why is my theme email template override not working?
The most common reason is an Admin template assigned to the same email. Admin templates take precedence over theme files. Check Stores, Configuration, Sales, Sales Emails at every scope. Also confirm the override path matches the module name exactly, such as Magento_Sales/email/order_new.html, and clean caches.
Can I still call methods like order.getCustomerName() in email templates?
Not in current Magento 2.4. Strict mode, the default since 2.4.0, does not resolve method calls in var directives. Use the data keys the sender provides, such as order_data.customer_name. Objects extending DataObject can still be read with getter-style syntax, which Magento maps to getData with the matching key.
Where do I enable asynchronous order emails in Magento 2?
Go to Stores, Configuration, Sales, Sales Emails, General Settings and set Asynchronous sending to Enable. Emails are then sent by cron jobs such as sales_send_order_emails, which core schedules to run every minute in the default cron group. The Limit per cron run setting defaults to 50.
Why did order confirmation emails stop after enabling async sending?
Almost always because cron is not running, or the default cron group is stuck. With async sending enabled, nothing is sent at checkout. Check the cron_schedule table for sales_send_order_emails entries and their status, and confirm your server runs bin/magento cron:run every minute.
How do I style transactional emails on a Hyva theme?
Magento emails still use LESS through the inlinecss and css directives, even on a Hyva storefront. Follow Hyva’s email styling preparation step to copy the email LESS files into your theme, then customize them, or use Hyva’s documented approach that compiles Tailwind styles into a LESS file for emails.





