MJML: Why It Works and What Its Limits Are

MJML is an open-source markup language that compiles into the table-based HTML that email clients require. Our MJML glossary entry covers the basic definition.

If you switch email editors later, this format keeps your existing templates still usable. An editor built on MJML can hand you the MJML source, and any other MJML tool can open and edit it. An editor built on its own format can usually export finished HTML, but not an editable file that anything else understands.

Email HTML is stuck in the past for one main reason: the clients that display it never agreed on a rendering engine. Classic Outlook for Windows renders email with Microsoft Word's engine, a constraint Microsoft documents itself in Word's HTML and CSS rendering capabilities in Outlook. Word does not support floats, positioning, or much of the CSS box model, so a layout that any browser handles collapses inside Outlook.

The reliable common denominator across clients is the HTML table, styled inline, patched with client-specific exceptions. The problem with it is reviewability: the layout logic drowns in boilerplate, so reading a change means reading past hundreds of lines that never vary. We've written a separate guide about what goes wrong when it is done badly: why your email looks broken in Outlook.

MJML moves this workload into a compiler. A team of Mailjet developers created it in early 2015 for exactly this reason, and it has been MIT-licensed and open source from the start. You maintain a small readable file, and the generated table markup becomes the compiler's problem.

This is a complete MJML document: a logo, a paragraph, and a button. Thirteen lines, 418 bytes.

Compiled with mjml-cli 5.4.0, this document becomes 147 lines of HTML containing six nested <table> elements, five Outlook-only conditional blocks (<!--[if mso]>), and two media queries. The single <mj-button> line compiles to a table wrapping an anchor tag carrying thirteen inline style properties, including mso-padding-alt, a property that exists only for Word's renderer.

None of the output is content. It is the scaffolding email clients require, and the compiler regenerates it identically on every build, so a template that renders correctly today will still render correctly after the next edit.

The pipeline behind MJML is worth knowing before you adopt the framework. The compiler parses the document, hands each mj-* tag to a component that knows its own table-based equivalent, wraps column structures in Outlook conditional comments, inlines the styles, and emits media queries for the mobile layout. The official MJML documentation specifies each component's attributes and is the place to start a real file.

In our experience, the limits of MJML are:

• One breakpoint. MJML's responsive behavior is a single default breakpoint at 480 pixels, defined in the compiler's source and configurable through mj-breakpoint. Layouts are desktop or mobile. A three-tier layout that adapts separately for tablets is not what the framework is built to express.

• No logic. There are no loops, conditionals, or variables. MJML is markup, and personalization or repeated blocks belong to whatever templating layer sits on top of it, such as Handlebars, Liquid, or your backend's renderer. This division is deliberate, and it means MJML alone is not a complete templating answer.

• No translations. Nothing in the framework manages language variants. A template in five languages is five files, or one file plus your own string substitution. How Topol handles this in one template is covered in multilingual templates.

• Output size. Compiled output is several times the size of its source. Gmail clips messages above 102KB, so a very long email assembled from many compiled sections can hit the ceiling sooner than its source size suggests.

• Custom components mean JavaScript. Extending the tag set is supported and documented, and it means writing a component class against the compiler's API rather than adding a snippet of markup.

• Version 5 raised the floor. The v5.0.0 release in April 2026 replaced the minifier toolchain, tightened mj-include handling, and dropped Node 16 and 18 support, so older build pipelines need to be reviewed before upgrading.

Yes. The project is MIT-licensed with 18,000+ GitHub stars, and its release history is public, so the current version and the date of the last commit are always visible.

When a client changes its rendering behavior, the fix lands in a public repository you can read, patch, or pin, rather than inside a vendor's closed generator on the vendor's timeline.

In Topol's editor, designs built visually compile through MJML, and templates export as MJML files. The export is the mechanism that keeps the decision reversible, because you can move the templates to another MJML tool. For SaaS teams, Topol Plugin embeds the editor inside your own product, so your customers edit templates without your engineers building an editor. The embeddable email editor evaluation guide covers how to choose an editor that's right for your SaaS product.

Mailjet Markup Language. A team of Mailjet developers created the framework in early 2015, and it has since become an open standard used well beyond Mailjet's own products.

Yes. The framework is open source under the MIT license, which permits commercial use, modification, and redistribution. The compiler, the component set, and the documentation are all public.

Not reliably. Compilation is one-way, and no maintained tool reconstructs MJML from table-based HTML with dependable results. The realistic paths are rebuilding the template section by section or starting from an existing MJML template and porting the content.

One breakpoint at 480 pixels by default: above it columns sit side by side, below it they stack. The mj-breakpoint head tag changes the value, and the single-breakpoint model itself is a design constraint of the framework.

The maintained alternatives take different bets: react-email builds messages as React components and fits only that ecosystem, Maizzle keeps you in HTML styled with Tailwind classes, and Foundation for Emails is the longest-running, built on Sass. MJML remains the only one of the four that visual editors also read and write, which is what makes its files portable between tools.

No. The framework is also the compilation layer inside visual editors, so a team can get MJML's rendering and portability while non-developers do the editing. Writing it by hand is a workflow choice for teams where engineers own email.