I added a custom .html email template at THEME\Magento_Email\email\usp_block.html (i also tried THEME\Magento_Email\view\frontend\email\usp_block.html).

Then I added the file THEME/etc/email_templates.xml with this content:

<?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="design_email_usp_block_template" label="USP Block" file="usp_block.html" type="html" module="Magento_Email" area="frontend"/>

Now I added a new template in the Magento Backend at Marketing -> E-Mail Templates and tried to include my template like this:

{{template config_path="design/email/usp_block_template"}}

Then I flushed the cache. But if I preview, then I get this:

Error while filtering the template: The email template 'design_email_usp_block_template' is not defined.

2 Answers 2


I think that what you are trying to do is something similar to how the header and footer blocks are inserted inside email templates. However, for these 2 blocks have their path defined as a system configuration path, it's not a naming convention (see vendor/magento/module-email/etc/di.xml enter image description here

In vendor/magento/framework/Filter/Template.php you have enter image description here

So what I get from this is that if you want to include your custom block the same way that the email header&footer are, as global blocks, then it means that you also have to define it the same way, by declaring the config path where this template is registered and saving the values, given the instruction <PATH> equals the XPATH to the system configuration value that contains the value of the template. Which means that you need a custom module for creating this new global block.

But I am not sure you actually need it to be a global block, you could add a simple email template and load it in admin (select template from dropdown and click button 'load template').

Check this link https://magento.stackexchange.com/a/179107/35330 that can help you. Worth to mention that the 'module' property inside email_templates.xml should point to your custom module, not Magento_Email, or otherwise it will try to look for it inside Magento_Email module and once again, not find it.

  • Thank you, loading it from the dropdown ist not an option for me. I want to insert a include statement into various templates, just like the header and footer are getting loaded. I try to figure out how I can copy the behaviour from header and footer so I can just insert my template anywhere, it is no where documented.
    – Black
    Mar 15, 2021 at 12:58
  • 1
    roger that. i recommend you check the magento module-email module and debug how they did it there. i also had to piece together some bits from that module in my answer above.
    – Diana
    Mar 15, 2021 at 13:03
  • 1
    yeah, i thought this wasn't easy.. sorry to hear this. have you also considered using a variable instead? docs.magento.com/user-guide/marketing/variables-custom.html
    – Diana
    Mar 15, 2021 at 14:21
  • 1
    no problem, wish i was more useful :)
    – Diana
    Mar 15, 2021 at 14:36
  • 1
    @Black can you please create a system configuration for "design/email/usp_block_template", no need to fetch it's value just create it and check if it works. Mar 15, 2021 at 15:11

The User aligent-skumar on GitHub provided the answer:

MODULE = app/code/NameSpace/ModuleName

  1. Create your template:


<div>This is a test</div>
  1. declare template in email_template.xml:


<?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="custom_email_usp_template" label="USP Block" file="usp.html" type="html" module="Magento_Email" area="frontend"/>
  1. Create layout file:


<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      label="Subscription renew notification email items" design_abstraction="custom">
    <block name="test.email.viewmodel" class="Magento\Framework\View\Element\Template" template="NameSpace_ModuleName::usp.phtml">
    <!-- OPTIONAL:
            <argument name="view_model" xsi:type="object">NameSpace\ModuleName\ViewModel\<ViewModelClass></argument>
  1. Define E-Mail template definieren MODULE\view\frontend\email\usp.html
 {{template config_path="design/email/header_template"}}
     {{layout handle="custom_email_usp_template" area="frontend"}}  <-- now you can include your template like this
 {{template config_path="design/email/footer_template"}}
  1. Now you can use your template in the backend:

Marketing -> Communication: E-Mail Templates -> Create new template.

You will find this in the dropdown now:

Magento E-Mail:

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.