Insert a block in order email confirmation template

Insert a block in order email confirmation template

August 18, 2026 · Illustrated author avatarBy Stefan Bogdanescu
Insert a block in order email confirmation template

Customizing Order Email Templates in Magento

When it comes to customizing order email templates in Magento, many developers find themselves struggling with inserting custom blocks containing specific parameters related to the order. This is often due to the complex structure of Magento’s template system and the various layout handles involved.

In your case, you’ve attempted to insert a new block named email.order within the sales_email_order_items layout handle using a PHTML template file called custom/order.phtml. While this might seem like a straightforward approach, Magento doesn’t recognize this block by default, leading to the “no way” issue you’re experiencing.

Understanding Magento’s Template System

Magento uses XML layouts to define the structure of its templates. These layouts are defined in files located under app/design/frontend/<package>/<theme>/layout. When an email is sent, Magento uses a specific layout file—usually located at app/code/core/Mage/Sales/etc/layouts.xml.

Solving the Block Insertion Issue

To successfully insert your custom block into the order confirmation email template, you need to follow these steps:

  1. Create Your Custom PHTML Template

Ensure that your custom/order.phtml file is located in the correct directory. For theme-specific templates, this would typically be under app/design/frontend/<package>/<theme>/template/email.

  1. Define the Block in Your Module’s Layout XML

Instead of trying to define the block directly within an existing layout handle like sales_email_order_items, you should create a new layout file for your custom module.

  • Create a new directory named layout under your module’s main directory (e.g., app/code/local/YourCompany/YourModule).

  • Inside this layout directory, create a new XML file for the sales order emails, e.g., sales_order_shipment_email.xml.

Here’s an example of what this file could look like:

<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:App/etc/layout.xsd">
    <layout version="1.0">
        <update handle="sales_email_order_items"/>
        <reference name="items">
            <action method="unsetChildren"/>
            <block type="page/html_wrapper" name="email.order" translate="label" template="custom/order.phtml">
                <block type="yourcompany_yourmodule/your_custom_block_type" name="your_custom_block" template="custom/your_custom_template.phtml"/>
            </block>
        </reference>
    </layout>
</config>
  1. Define Your Custom Block Type

In the above XML, replace yourcompany_yourmodule/your_custom_block_type with an actual block type from your module. You’ll need to create this block type in your module’s configuration file (etc/config.xml).

  1. Clear Magento Cache

After making these changes, clear your Magento cache using the command line or via the admin interface. This will ensure that Magento re-parses the layout files and recognizes your new block.

Conclusion

Customizing order email templates requires a deep understanding of Magento’s XML layout system and block types. By following this approach—creating a custom PHTML template, defining it in your module’s layout XML file, and ensuring the corresponding block type is defined—you should be able to successfully insert your custom block into the order confirmation email.

Remember, when working with Magento templates, patience and careful testing are key. Always check your work in a development environment before pushing changes live.

For more detailed information on customizing Magento emails, I recommend checking out Laravel Company’s guide on Magento Email Templates. This comprehensive resource provides step-by-step instructions and best practices for working with Magento’s email templates.

Extensions Themes Email Orders

Our network