Install

Installation

You can install MJML with NPM to use it with NodeJS or the Command Line Interface. If you're not sure what those are, head over to Usage for other ways to use MJML.

npm install mjml

Development

To work on MJML, make changes and create pull requests, download and install yarn for easy development.

git clone https://github.com/mjmlio/mjml.git && cd mjml
yarn
yarn build

You can also run yarn build:watch to rebuild the package as you code.

Usage

Online

Don't want to install anything? Use the free online editor!

Applications and plugins

MJML comes with an ecosystem of tools and plugins, check out:

• Visual Studio Code plugin (MJML is included). Also available at Visual Studio Code Marketplace and the Open VSX Registry or in the extensions tab of the Visual Studio Code app.
• Sublime Text plugin (MJML needs to be installed separately)

For more information, check the Tooling section.
For more tools, check the Community page.

Command line interface

Compiles the file and outputs the HTML generated in output.html

mjml input.mjml -o output.html

You can pass optional arguments to the CLI and combine them.

Minify options compatibility

CSS minification is controlled via minifyCss. For backward compatibility, the legacy minifyCSS key is still accepted and mapped internally:

• Disable CSS minification:

mjml input.mjml -o output.html --config.minify true --config.minifyOptions '{"minifyCss": false}'
# legacy:
mjml input.mjml -o output.html --config.minify true --config.minifyOptions '{"minifyCSS": false}'

• Enable CSS minification with presets or options:

# lite preset
mjml input.mjml -o output.html --config.minify true --config.minifyOptions '{"minifyCss": "lite"}'
# legacy equivalent (maps to lite)
mjml input.mjml -o output.html --config.minify true --config.minifyOptions '{"minifyCSS": true}'
# default preset with single quotes for strings
mjml input.mjml -o output.html --config.minify true --config.minifyOptions '{"minifyCss": {"preset":["default", {"normalizeString":{"preferredQuote":"single"}}]}}'

Inside Node.js

import mjml2html from 'mjml'

/*
  Compile an mjml string
*/
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,
  )

  /*
    Print the responsive HTML generated and MJML errors if any
  */
  console.log(htmlOutput)
}

renderMjml()

You can pass optional options as an object to the mjml2html function:

minifyCss can be false, lite, default, or a cssnano preset object, for example minifyCss: { preset: ['default', { normalizeString: { preferredQuote: 'single' } }] } | | mjmlConfigPath | string | The path or directory of the .mjmlconfig file | process.cwd() | | preprocessors | array of functions | Preprocessors applied to the xml before parsing. Functions must be (xml: string) => string | [] | | sanitizeStyles | boolean | Optional setting when using templating syntax to sanitize the input to PostCSS preventing errors | false | | templateSyntax | array of objects | When sanitizeStyles is true, you can pass optional syntax e.g. templateSyntax: [{ prefix: '{{', suffix: '}}' }, { prefix: '{=', suffix: '=}' }] | [{"prefix":"{{","suffix":"}}"},{"prefix":"[[","suffix":"]]"}] | | useMjmlConfigOptions | boolean | Allows to use the options attribute from .mjmlconfig file | false | | validationLevel | string | Available values for the validator: strict soft skip | soft |

Include path examples

Includes are ignored by default for security (ignoreIncludes: true). Enable them explicitly and scope allowed folders with includePath.

CLI example:

$> mjml template.mjml \
  --config.filePath /project/templates/newsletter \
  --config.allowIncludes true \
  --config.includePath '["../_common","../vendor"]'

• Single include directory

import mjml2html from 'mjml'

async function compileOne(source) {
  const { html, errors } = await mjml2html(source, {
    ignoreIncludes: false,
    filePath: '/project/templates/campaignA/email1.mjml',
    includePath: '/project/templates/_common',
  })
}

• Multiple include directories

async function compileMany(source) {
  const { html, errors } = await mjml2html(source, {
    ignoreIncludes: false,
    filePath: '/project/templates/campaignA/email1.mjml',
    includePath: ['/project/templates/_common', '/project/templates/_footers'],
  })
}

Security notes:

• Includes are ignored by default (ignoreIncludes: true). Enable explicitly and scope allowed folders with includePath.
• Paths are fully URL-decoded before validation (handles double/triple encoding like %252F).
• Early rejects: absolute paths, UNC-style paths (//server/... or \\server\\...), Windows drive letters (C:\...), and null bytes (%00).
• Canonical boundary checks: we resolve and follow symlinks with realpath and require the target to stay inside filePath or any includePath roots.

Best practices for shared partials

• Project templates root: Set filePath to your templates root and write includes relative to that base (e.g., ./_common/header.mjml). Simple setup; templates must use base-relative paths.
• Explicit allowlist: Keep template-relative paths (e.g., ../_common/header.mjml) and declare includePath with sibling/shared folders. No template changes; supports multiple shared roots.
• Security: Only files under filePath and includePath are allowed. Absolute paths outside these roots and .. escapes are denied.

API

A free-to-use MJML API is available to make it easy to integrate MJML in your application. Head over here to learn more about the API.