MJML: Why we created a new open-source framework for email coding

How it all started

We’ve helped businesses send over 20 billion emails over the past 5 years, with one key objective in mind: deliverability. It’s crucial that our users’ email sends get in front of their recipient’s eyes, especially since deliverability directly impacts ROI.  

In addition to deliverability, one of the key ingredients for engagement is user experience. In a world where 50% of email is read on mobile, building responsive email is ever important.   That’s why in 2015, we launched Passport, a drag-and-drop tool that would make building responsive email even easier for our users.

On the surface, Passport allows users a quick way to build email simply by dragging and dropping, but behind the scenes an engine translates those actions into a responsive HTML template. Technically speaking, the email is "described" to the engine in JSON and then the engine translates this into responsive HTML code. More precisely, the email is “described” in JSON to the engine that outputs responsive HTML accordingly.

We quickly realized this engine could have an even more powerful impact outside of Passport. What if, we put the tool at its core in the hands of our users? What if we let them talk directly with the engine? That’s what we decided to do. And to make it more user-friendly, we decided to replace the JSON description with a markup language so it’s almost like HTML. So the principles are familiar - like the ever-familiar HTML - but pain-free, responsive by design and semantic. We created tags like <mj-section> and <mj-column>, that makes it pretty easy and quick to design email just the way you want.

From a markup language to a library of components

Email has a wide range of use cases: weekly digests, welcome emails, invoices…the list goes on. While it might not be possible to sum up all the different types of email campaigns, the actual content structure is very similar. The core of a responsive email is a one column layout. But, when you build this out with HTML, it can become lengthy, repetitive and frankly - a pain.

Let’s take the invoice for example, best case scenario, you’ll get something like this:

The good news is that the MJML engine is based on React.js, which allows to use and create components. See what we did here? Yes, MJML enables you to create your own <mj-invoice> and <mj-item> components to replace that scary looking code above with:   All generated HTML will also be compliant with the most popular email clients.

Giving back to the community

At the end of the day, we wouldn’t have been able to build MJML without what we learned from you, our community. Keeping that technology to ourselves simply wouldn’t have been fair. That’s why we made MJML open-source under the MIT license, so that the community can easily leverage the powerful engine that has been living inside Passport for one year. The MIT license is incredibly open and simple. Unlike the GPL license, it allows you to use MJML in a bigger application without having to make the whole application open-source.

This means that you can use MJML to design HTML emails or even integrate the MJML engine into a product of your choice but also continue to help us improve on it and build it out with us. If you’d like to know more about how MJML works, head over to the documentation.

To make it better, you are welcome to contribute to the engine and help us make sure that the HTML output from MJML is perfect and consistent with as many email clients as possible. We’re hoping the richness and variety of MJML components will inspire you to continue creating even more exciting ones, matching your own needs (from a corporate email header re-used across all your email communications to more specialised ones for your business) . If you miss any component, the best thing you can do is create it so other people can use it too! We’ll regularly review PR requests on Github to add components from the community. Our ambition is to make MJML grow with our community so that it gets even better over time. It will also be regularly updated to integrate any change in HTML rendering from popular email clients so that you can stay ahead of the email game!