Guide · Open source

How to use MJML: install, compile and send responsive email

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

MJML is an open-source markup language, created by Mailjet, for building responsive HTML emails with less effort. You write simpler semantic tags and its engine translates them into the responsive HTML email clients need. This guide shows how to install MJML, compile a template from the command line or Node.js, and tune the output.

MJMLmjmlio/mjml · ★ 18.3k · MIT Install options & downloads

Quick start

1Check Node.js. MJML needs Node.js. Confirm it is installed before you start.
2Install MJML. Run npm install mjml in your project folder.
3Write an MJML file. Create input.mjml with an mjml root, an mj-body, and mj-section and mj-column tags around your content.
4Compile to HTML. Run mjml input.mjml -o output.html to produce responsive HTML.
5Watch while editing. Use mjml -w input.mjml to recompile whenever the file changes.
6Use it in code. Call mjml2html with your MJML string from Node.js and handle the returned HTML.

What MJML is and who it is for

MJML is a markup language designed to reduce the work of coding a responsive email. Its semantic syntax is easier to read than nested email HTML tables, and its standard components library shortens development time.

MJML targets email output. If you only need a plain-text or single-page web layout, it is not the right tool.

Developers who build transactional or marketing emails by hand
Teams that need emails to display well on phones and desktop clients
Anyone who wants to try it in the browser before installing

Install MJML with npm

MJML is installed with npm and works with Node.js or the Command Line Interface. The prerequisite is Node.js. If you do not work with Node.js or the command line and want no setup, use the online editor instead.

npm install mjml

Try MJML online without installing anything

The README points to a free online editor, available at mjml.io/try-it-live. It is the quickest way to see how MJML tags turn into HTML before you set up a project.

Compile a template from the command line

Run the CLI with an input file and the -o flag to write the generated HTML to an output file. The example below compiles input.mjml into output.html.

You can also use -s to write output to stdout, or -w to watch a file or folder for changes. Config options such as --config.minify and --config.beautify are passed as flags.

mjml [input] -o [output] writes the output to a file
mjml [input] -s writes the output to stdout
mjml -w [input] watches a file or folder for changes
--config.beautify defaults to true; --config.minify defaults to false
--config.allowIncludes defaults to false and enables mj-include processing

mjml input.mjml -o output.html

Use MJML inside Node.js

Import the package and pass an MJML string to mjml2html. The function returns the rendered HTML, which you can log or send. You can also pass an options object as the second argument.

Useful options include beautify (default false in the API), ignoreIncludes (default true), keepComments (default true) and filePath, which sets the base path for relative mj-include paths.

beautify: boolean, beautifies the HTML output
ignoreIncludes: boolean, ignores mj-include instances (default true)
filePath: base path used for relative mj-include paths
keepComments: boolean, keeps comments in the output (default true)

import mjml2html from 'mjml'

async function renderMjml() {
  const htmlOutput = await mjml2html(`
    <mjml>
      <mj-body>
        <mj-section>
          <mj-column>
            <mj-text>
              Hello World!
            </mj-text>
          </mj-column>
        </mj-section>
      </mj-body>
    </mjml>
  `, options)

  console.log(htmlOutput)
}

renderMjml()

Tune the output and use editor tooling

The CLI accepts config flags for output control, including minification and template delimiters. Minification is off by default, so enable --config.minify when you want smaller output.

For editing, the README lists a Visual Studio Code plugin, where MJML is included, and a Sublime Text plugin, which needs MJML installed separately. More tools are on the Community page.

Visual Studio Code plugin: MJML is included
Sublime Text plugin: install MJML separately
Community page at mjml.io/community lists more tools

What people use it for

Sending transactional emails such as receipts or account notices from a Node.js app
Building marketing newsletters that must display well on phones and desktop clients
Keeping email templates readable instead of maintaining nested email HTML tables
Previewing and editing templates in the online editor before setting up a project

Frequently asked questions

How do I install MJML?

Install MJML with npm by running npm install mjml. The README lists Node.js as the prerequisite. If you do not want to install anything, the README points to the free online editor.

Is MJML free to use?

MJML is open source and released under the MIT licence, as stated in the project's README and listing. The online editor is described in the README as free.

What do I need to run MJML?

You need Node.js to use the npm package, and the command line interface for compiling files. Without Node.js or the command line, the README suggests using the online editor.

How do I convert MJML to HTML?

Run mjml input.mjml -o output.html from the command line, or call mjml2html with your MJML string in Node.js. Both produce the responsive HTML output.

Why is my MJML include not working?

mj-include processing is disabled by default. Enable it with --config.allowIncludes true on the CLI, or set ignoreIncludes to false in the Node.js options, and check that includePath and filePath point to the right folders.

What are the alternatives to MJML?

The README lists Foundation for Emails, maizzle and react-email as comparable projects. Choose based on whether you want a markup language, a framework or a React-based workflow.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

MJML suits developers and teams who build responsive emails by hand and want a readable template format, and it is free and open source under the MIT licence. If you only need a plain-text or single-page web layout, or you want no Node.js setup at all, pick the online editor or a different tool.

Install options & downloads