Customize Mail With HTML Templates

TemplateX compiles those files into the theme's woocommerce/emails/ override folder. WooCommerce still sends the email, passes the order variables, runs email hooks, and applies its normal mail settings.

Smallest Email Override#

Create a file that mirrors the WooCommerce email template path:

<?phpdefined('ABSPATH') || exit;do_action('woocommerce_email_header', $email_heading, $email);?><table role="presentation" width="100%" cellspacing="0" cellpadding="0">  <tr>    <td>      <h1><?php echo esc_html($email_heading); ?></h1>      <?php if (isset($order) && $order instanceof WC_Order) : ?>        <p>Thanks for your order #<?php echo esc_html($order->get_order_number()); ?>.</p>      <?php endif; ?>    </td>  </tr></table><?phpdo_action('woocommerce_email_order_details', $order, $sent_to_admin, $plain_text, $email);do_action('woocommerce_email_customer_details', $order, $sent_to_admin, $plain_text, $email);do_action('woocommerce_email_footer', $email);

This is still a TemplateX source view because it lives in resources/views, but email templates usually use native PHP for WooCommerce's email variables.

Choose The Template File#

WooCommerce loads email templates by path. Keep the same filename and folder shape WooCommerce expects:

Start by finding the matching template in WooCommerce's own templates/emails/ directory, then copy only the path you need into resources/views/woocommerce/emails/.

Keep the override small when possible. For example, override email-header.php, email-footer.php, or email-styles.php when the shared wrapper is enough. Override a specific customer or admin email only when that email needs different content.

Preserve WooCommerce Hooks#

WooCommerce and extensions add order details, customer details, payment information, shipping content, and extra messages through email hooks. If you replace a whole email template, keep the hooks you still need:

<?phpdo_action('woocommerce_email_order_details', $order, $sent_to_admin, $plain_text, $email);do_action('woocommerce_email_order_meta', $order, $sent_to_admin, $plain_text, $email);do_action('woocommerce_email_customer_details', $order, $sent_to_admin, $plain_text, $email);

Removing those hooks can also remove extension output. Be deliberate when you leave one out.

Use Order Data#

Inside WooCommerce order emails, use the variables WooCommerce passes to the template:

Example:

<?php if (isset($order) && $order instanceof WC_Order) : ?>  <p>    Order total:    <?php echo wp_kses_post($order->get_formatted_order_total()); ?>  </p><?php endif; ?>

Use escaping that matches the value. Use esc_html() for plain text, esc_url() for URLs, and wp_kses_post() for WooCommerce HTML.

HTML Email Rules#

Email HTML is not the same as frontend HTML:

• Use conservative markup.
• Prefer tables for structural layout.
• Keep important styles inline or in WooCommerce's email styles template.
• Test the email in real clients when the design matters.
• Do not depend on frontend JavaScript, Svelte islands, cart drawers, or browser-only CSS.

TemplateX Tags In Email Files#

TemplateX can compile normal TemplateX syntax in files under resources/views/woocommerce/emails/, but email templates are not product loop, cart, checkout, or account contexts.

Do not use {{ query:products }} or {{ cart:add }} as a shortcut for order email content. Use WooCommerce's $order object and email hooks so the email matches the actual order WooCommerce is sending.

Build Output#

A source file such as:

publishes as a native WooCommerce override:

The compiled PHP should work when the TemplateX plugin is inactive or absent.