Using MJML's <mj-include>

Familiar with MJML? If you are not familiar, then check out my tutorial on coding responsive emails with MJML before you read below.

I have praised MJML in the past and I will do it again. I have yet to find a better responsive email framework and cannot even begin to count the numbers of hours that I have saved by using this platform when creating newsletters. The list of reasons why I enjoy using the platform grows with each release, but one reason in particular stands out from the rest and that is “mj-include”. In my personal opinion, I find this function to be the most important feature of MJML despite the fact that it doesn’t actually output any HTML. It is simply a utility feature to make coding emails structured and clean. This might not see beneficial to someone building out their first email, but as many email coders will note, this ability is something that is not possible when writing and iterating on emails in plain HTML (Death by nested divs). Because of this, I will discuss the benefits of using this function, as well as a simple example of how it might fit within your own project.

“mj-include” is an MJML function that brings the common programming practice of modularizing code to the framework. Modularizing code means separating the functionality of the software into independent single-purpose pieces that can be easily added, removed, maintained and debugged without the hassle of scanning through files and lines of code for specific functionality.

This tag only contains a single attribute, “path”, but this attribute acts as a directory explorer and file importer. All that is needed to be inputted to utilize the tag is the path to the file that contains the code that you would like to be imported. From there, MJML will recognize this request as it gets processed and render the code from this file within the body or head of your email. It is as simple as that. With just a single tag, you now have the ability to apply the practice of modularizing your code within your MJML newsletter.

If you are wondering how this might look in the context of your email, then use my setup as a guide. The way I have modularized my code is by breaking apart each horizontal section of my newsletter from the head to the footer.

Here is my index.mjml which gets rendered into HTML:

        <!-- content -->
        <mj-wrapper background-color="#FFFFFF" border="1px solid #e0e0e0" padding="0 0 0 0">
            <mj-include path="./header" />
            <mj-include path="./message" />
            <mj-include path="./feature" />
            <mj-include path="./three-articles" />
            <mj-include path="./footer" />

This approach makes it easy for me to quickly understand the structure of my email as well as the files that I can access to modify just one particular section. If I wanted to change the code located within any of the files that are referenced by my tag, then I would check for the file within the parent directory of my project that contains the name located in the “path” attribute. E.g. would be feature.mjml. From here, all that is needed to be done is make my edits, reprocess the index.mjml file and the changes to the imported code will appear within my HTML email.

As you can see, the use of the MJML include tag should be a no-brainer when you write your next HTML email. With a single tag, you have the ability to import and exclude sections of code without the hassle of inadvertently removing additional code which might break the rest of your email. While my example was very simple and straight-forward, this tag can be used for more complex email scenarios that require componentizing certain elements within each section in your email. I will leave it up to you to think about all of the possible approaches you might be able to make with the tag, but the more you use this tag, the more your emails will be structured and maintainable.