NAV

Responsive Email Patterns

MJML

MJML Guides

MJML is a markup language designed to reduce the pain of coding a responsive email. Its semantic syntax makes it easy and straightforward and its rich standard components library speeds up your development time and lightens your email codebase. MJML’s open-source engine generates high quality responsive HTML compliant with best practices.

Overview

MJML rolls up all of what Mailjet has learned about HTML email design over the past few years and abstracts the whole layer of complexity related to responsive email design.

Get your speed and productivity boosted with MJML’s semantic syntax. Say goodbye to endless HTML table nesting or email client specific CSS. Building a responsive email is super easy with tags such as <mj-section> and <mj-column>.

MJML has been designed with responsiveness in mind. The abstraction it offers guarantee you to always be up-to-date with the industry practices and responsive. Email clients update their specs and requirements regularly, but we geek about that stuff - we’ll stay on top of it so you can spend less time reading up on latest email client updates and more time designing beautiful email.


<mjml>
  <mj-body>
    <mj-container>
      <mj-section>
        <mj-column>
          <mj-text>Hi sexy!</mj-text>
        </mj-column>
      </mj-section>
    </mj-container>
  </mj-body>
</mjml>




sexy

mjml

A MJML document starts with a <mjml> tag, it can contain only mj-head and mj-body tags. Both have the same purpose of head and body in a HTML document.

mj-head

mj-head contains everything related to the document such as style and meta elements. It supports custom head elements and can be registered through registerMJHeadElement(<string> name, <function> handler) api from mjml-core, it acts as a pre-render hook.

mj-body

mj-body contains everything related to the content of your email. It supports custom elements too and can be registered either through registerMJElement(<MJMLElement> class) api from mjml-core or via a .mjmlconfig file. Non-known element from mjml-core are simply ignored. Note that mj-body should have only one root element due to how React works.

mj-include

The mjml-core package allows you to include external mjml files to build your email template.

<!-- header.mjml -->
<mj-section>
  <mj-column>
    <mj-text>This is a header</mj-text>
  </mj-column>
</mj-section>

You can wrap your external mjml files inside the default mjml > mj-body > mj-container tags to make it easier to preview outside the main template

<!-- main.mjml -->
<mjml>
  <mj-body>
    <mj-container>
      <mj-include path="./header" /> <!-- or 'header.mjml' -->
    </mj-container>
  </mj-body>
</mjml>

The MJML engine will then replace your included files before starting the rendering process

Installation

# Install with npm in a folder where you will use MJML
$> npm install mjml

# In the folder where you installed MJML you can now run:
$> ./node_modules/.bin/mjml -V

# To avoid typing ./node_modules/.bin/, add it to your PATH (add it to .bashrc or .zshrc so you don't have to export it anymore):
$> export PATH="$PATH:./node_modules/.bin"

# You can now run MJML directly, in that folder:
$> mjml -V

MJML engine is written in NodeJS, leveraging ReactJS. We recommend installing and using MJML locally from NPM.

Command Line Interface

In addition to the translation engine, which converts MJML to email HTML, we’ve bundled a Command Line Interface (CLI) helping you to achieve the basic features it offers and integrate it seamlessly in your development flow.

Render a single file


$> mjml input.mjml

It will output an HTML file called a.html.

Render and redirect the result to a file


$> mjml input.mjml -o my-email.html

# or

$> mjml input.mjml --output my-email.html

You can output the resulting email responsive HTML in a file. If the file does not exist, it will be created.

Watch changes on a file


$> mjml -w input.mjml

# or

$> mjml --watch input.mjml

If you like live-coding, you might want to use the -w option that enables you to re-render your file every time you save it. It can be time-saving when you can just split you screen and see the HTML output modified when you modify your MJML.

Of course, the -w option can be used with an --output option too.

Getting Started

This is a responsive email

layout

Like a regular HTML template, we can split this one into different parts to fit in a grid.

The body of your email, represented by the mj-container tag contains the entire content of your document:

body

From here, you can first define your sections:

sections

Inside any section, there should be columns. Columns are what makes MJML responsive. They automatically re-organize themselves to fit perfectly on mobile and desktop.

columns

Below, you’ll find some basic rules of MJML to keep in mind for later. We’ll remind them when useful but better start learning them early on.

Column sizing

Auto sizing

As we mentioned earlier, sections are made of columns (up to 4 at this stage).

The default behavior of the MJML translation engine is to divide the section space (max 600px) in as many columns as you declare (always up to 4).

Let’s take the following layout to illustrate this: html <mjml> <mj-body> <mj-container> <mj-section> <mj-column> <!-- First column content --> </mj-column> <mj-column> <!-- Second column content --> </mj-column> </mj-section> </mj-container> </mj-body> </mjml>

Since the first section defines only 2 columns, the engine will translate that in a layout where each column takes 50% of the total space (300px each). If we add a third one, it goes down to 33%, and with a fourth one to 25%.

Manual sizing

If you need to go above 4 or manually set the column size, it is possible but the auto sizing mechanism described above does not apply anymore, meaning that the engine won’t automatically adapt the remaining space.

Let’s take the following layout to illustrate this: html <mjml> <mj-body> <mj-container> <mj-section> <mj-column width="300px"> <!-- First column content --> </mj-column> <mj-column> <!-- Second column content --> </mj-column> </mj-section> </mj-container> </mj-body> </mjml> In that case, the engine won’t set the second column width to 300px as one could expect. Once you decide to set manually the size of at least one column, you have to set manually each column size. Always keep in mind that the maximum space to end up with a responsive layout is 600px. This is a known limitation of the engine at the moment that we’re working to improve in a future release.

Nesting

<mjml>
  <mj-body>
    <mj-container>
      <mj-section>
        <mj-column>
          <!-- Column content -->
        </mj-column>
      </mj-section>
    </mj-container>
  </mj-body>
</mjml>

As we’ll discover in the next section, a basic MJML layout is:

Inside a column, you can include any standard component, or the ones you’ve defined and registered, but you can’t include columns or sections. This is a known limitation of the engine at the moment that we’re working to improve in a future release.

Tag styling

As we’ll discover later on in this documentation, each MJML tag (component) defines a set of attributes allowing you to change their final visual aspect. Since an MJML tag (component) translates into 1 to N HTML tags, it is not an easy task to match all the CSS rules one would like to define. This is the reason why components only offer a limited set of known attributes to modify their visual aspect and not the full range of CSS properties.

Following the Don’t Repeat Yourself DRY principle, you might not want to repeat the styling in each tag. You might simply want to define the style once and have it apply everywhere you decide (like CSS rules). For now, you must repeat for each tag the style you want to apply on it. Another way to achieve this is to create your own component, sub-classing a standard one and have your styles defined by default.

At this stage, the translation engine does not support to define styling attributes once in the layout and refer to it later and accept a larger range of CSS rules. These are improvements we’re working on for future releases.

Basic Layout

In this section, you’re going to learn how to code a basic email template using MJML.

Here is the final render we want to end with:

sexy

sexy

Looks cool, right?

Sections

<mjml>
  <mj-body>
    <mj-container>

      <!-- Company Header -->
      <mj-section background-color="#f0f0f0"></mj-section>

      <!-- Image Header -->
      <mj-section background-color="#f0f0f0"></mj-section>

      <!-- Introduction Text -->
      <mj-section background-color="#fafafa"></mj-section>

      <!-- 2 columns section -->
      <mj-section background-color="white"></mj-section>

      <!-- Icons -->
      <mj-section background-color="#fbfbfb"></mj-section>

      <!-- Social icons -->
      <mj-section background-color="#f0f0f0"></mj-section>

    </mj-container>
  </mj-body>
</mjml>

First, we will implement the skeleton which are the sections. Here, our email is going to be divided into 6 sections.

Company Header


<!-- Company Header -->
<mj-section background-color="#f0f0f0">
  <mj-column>
    <mj-text  font-style="italic"
              font-size="20"
              color="#626262">
      My Company
    </mj-text>
  </mj-column>
</mj-section>

The first section of the email consists in a centered banner, containing only the company name. The following markup is the MJML representation of the layout we want to obtain.

The text padding represents the inner space around the content within the mj-text element.

Image Header


<!-- Image Header -->
  <mj-section background-url="http://1.bp.blogspot.com/-TPrfhxbYpDY/Uh3Refzk02I/AAAAAAAALw8/5sUJ0UUGYuw/s1600/New+York+in+The+1960's+-+70's+(2).jpg"
              background-size="cover"
              background-repeat="no-repeat">

    <mj-column width="600">

          <mj-text  align="center"
                color="#fff"
                font-size="40"
                font-family="Helvetica Neue">Slogan here</mj-text>

      <mj-button background-color="#F63A4D"
                 href="#">
        Promotion
      </mj-button>

    </mj-column>

  </mj-section>

Next comes a section with a background image and a block of text (representing the company slogan) and a button pointing to a page listing all the company promotions.

To add the image header, you will have to replace the section’s background-color by a background-url. Similarly to the first header, you will have to center the text both vertically and horizontally. The padding remains the same. The button href sets the button location. In order to have the background rendered full-width in the column, set the column width to 600px with width="600".

Introduction Text


<!-- Intro text -->
  <mj-section background-color="#fafafa">
        <mj-column width="400">

          <mj-text font-style="italic"
                   font-size="20"
                   font-family="Helvetica Neue"
                   color="#626262">My Awesome Text</mj-text>

            <mj-text color="#525252">
                Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin rutrum enim eget magna efficitur, eu semper augue semper. Aliquam erat volutpat. Cras id dui lectus. Vestibulum sed finibus lectus, sit amet suscipit nibh. Proin nec commodo purus. Sed eget nulla elit. Nulla aliquet mollis faucibus.
          </mj-text>

            <mj-button background-color="#F45E43"
                     href="#">Learn more</mj-button>

    </mj-column>
  </mj-section>

The introduction text will consist of a title, a main text and a button. The title is a regular mj-text that can be customized.

2 Columns Section


<!-- Side image -->
<mj-section background-color="white">

  <!-- Left image -->
  <mj-column>
    <mj-image width="200"
              src="https://designspell.files.wordpress.com/2012/01/sciolino-paris-bw.jpg" />
  </mj-column>

  <!-- right paragraph -->
  <mj-column>
    <mj-text font-style="italic"
             font-size="20"
             font-family="Helvetica Neue"
             color="#626262">
        Find amazing places
      </mj-text>

      <mj-text color="#525252">
        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin rutrum enim eget magna efficitur, eu semper augue semper. Aliquam erat volutpat. Cras id dui lectus. Vestibulum sed finibus lectus.</mj-text>

  </mj-column>
</mj-section>

This sections is made up of 2 columns. One containing an image, the other one containing a text. For the image part, note that when a tag does not have any child, you can use the XML self-closing tag syntax: <mj-image />

For the text part, you are going to need two <mj-text>s like above. One with a title format, and the other one as a regular text.

Icons

<!-- Icons -->
<mj-section background-color="#fbfbfb">
  <mj-column>
    <mj-image width="100" src="http://191n.mj.am/img/191n/3s/x0l.png" />
  </mj-column>
  <mj-column>
    <mj-image width="100" src="http://191n.mj.am/img/191n/3s/x01.png" />
  </mj-column>
  <mj-column>
    <mj-image width="100" src="http://191n.mj.am/img/191n/3s/x0s.png" />
  </mj-column>
</mj-section>

This section is a 3-columns-based section. Please notice you can make the padding vary to change the space around the images.

Social Icons


<mj-section background-color="#e7e7e7">
  <mj-column>
      <mj-social display="facebook" />
  </mj-column>
</mj-section>

The MJML standard components library comes with a mj-social component. By default, every social network is enabled. To disable some of them, just use their names as an attribute with a false value. Here, we’re going to use facebook only.

Newsletter Layout

In this section, you’re going to build a newsletter template. The final result will look like this

sexy

sexy

Structuring

<mjml>
  <mj-body>
    <mj-container>

      <!-- Header -->
      <mj-section></mj-section>

      <!-- Banner -->
      <mj-section></mj-section>

      <!-- Article -->
      <mj-section></mj-section>

      <!-- Editor Header -->
      <mj-section></mj-section>

      <!-- Editor Image -->
      <mj-section></mj-section>

      <!-- Article -->
      <mj-section></mj-section>

      <!-- Social -->
      <mj-section></mj-section>

    </mj-container>
  </mj-body>
</mjml>

Similarly to the basic layout above, you will have to first divide your template into sections.


<!-- Header -->
<mj-section padding-bottom="0" background-color="white">
  <mj-column width="100%">
    <mj-image src="https://avatars0.githubusercontent.com/u/16115896?v=3&s=200" width="50px"/>

      <mj-divider
          padding-top="20"
          padding-bottom="0"
          padding-left="0"
          padding-right="0"
          border-width="1px"
          border-color="#f8f8f8"/>
  </mj-column>
</mj-section>

The header can be easily done with a regular mj-image. We also want a thin border that can be added with an mj-divider. This component acts as a CSS border. Notice that some components such as the mj-section and mj-divider come with default padding values.


<!-- Banner -->
<mj-section padding-bottom="0" background-color="#fcfcfc">
  <mj-column width="100%">
    <mj-text align="center" font-size="20" color="grey" font-family="Helvetica Neue" font-weight="200">
    Here is what you've missed
      </mj-text>
      <mj-divider
          padding-top="20"
          padding-bottom="0"
          padding-left="0"
          padding-right="0"
          border-width="1px"
          border-color="#f8f8f8"/>
  </mj-column>
</mj-section>

For the banner, we want the same divider, with an mj-text.

Article

The article’s columns need to be manually sized. By default, the values are considered to be in pixels (px). The first column contains an image, while the second contains both the title and the paragraph. the two mj-texts are aligned to the left.

Editor


<!-- Editor -->
<mj-section padding-bottom="0">
  <mj-column>
    <mj-text font-size="20" color="rgb(165, 176, 184)">
        Explore our new features
      </mj-text>
  </mj-column>
</mj-section>

<mj-section padding-top="0">
  <mj-column width="600">
    <mj-image src="https://cloud.githubusercontent.com/assets/6558790/12450760/ee034178-bf85-11e5-9dda-98d0c8f9f8d6.png"/>
  </mj-column>
</mj-section>

Note here that colors can be expressed using different formats (rgb, hsl, hex etc.).

Social


<mj-section background-color="#f3f3f3">
  <mj-column>
    <mj-text>Stay in touch!</mj-text>
      <mj-social
          mode="vertical"
          display="twitter facebook" />
  </mj-column>
</mj-section>

Finally, as our previous example, the social part will be a vertically aligned mj-social.

Components

Components are the core of MJML. A component is an abstraction of a more complex email-responsive HTML layout. It exposes attributes, enabling you to interact with the final component visual aspect.

MJML comes out of the box with a set of standard components to help you build easily your first templates without having to reinvent the wheel.

For instance, the mj-button components is, on the inside, a complex HTML layout:


<!-- MJML -->
<mj-button href="#">
    Hello There!
</mj-button>

<!-- HTML -->
<table cellpadding="0" cellspacing="0" style="border:none;border-radius:3px;" align="center">
    <tbody>
        <tr>
            <td style="background-color:#414141;border-radius:3px;color:#ffffff;cursor:auto;" align="center" valign="middle" bgcolor="#414141">
                <a class="mj-content" href="#" style="display:inline-block;text-decoration:none;background-color:#414141;border:1px solid #414141;border-radius:3px;color:#ffffff;font-size:13px;font-weight:bold;padding:15px 30px;" target="_blank">
                    Hello There!
                </a>
            </td>
        </tr>
    </tbody>
</table>

Standard Head components

Head components ease your development process, enabling you to import fonts, define default styles or create classes for MJML components among others.

mjml-attributes

This tag allows you to modify default attributes on a mj-tag and add mj-class to them.

 <mjml>
   <mj-head>
     <mj-attributes>
       <mj-text padding="0" />
       <mj-class name="blue" color="blue" />
       <mj-class name="big" font-size="20px" />
       <mj-all font-family="Arial" />
     </mj-attributes>
   </mj-head>
   <mj-body>
     <mj-container>
       <mj-section>
         <mj-column>
           <mj-text mj-class="blue big">
             Hello World!
           </mj-text>
         </mj-column>
       </mj-section>
     </mj-container>
   </mj-body>
 </mjml>

sexy

mjml-style

This tag allows you to set CSS styles that will be applied to the HTML in your MJML document as well as the HTML outputted. The CSS styles will be added to the head of the rendered HTML by default, but can also be inlined by using the inline="inline" attribute.

  <mjml>
    <mj-head>
      <mj-style>
        @media all and (max-width: 480px) {
          div[style*="color:#F45e46;"] {
            text-align: center !important
          }
        }
      </mj-style>
      <mj-style inline="inline">
        .link-nostyle {
          color: inherit;
          text-decoration: none
        }
      </mj-style>
    </mj-head>
    <mj-body>
      <mj-container>
        <mj-section >
          <mj-column>

            <mj-image width="100" src="/assets/img/logo-small.png"></mj-image>

            <mj-divider border-color="#F45E43"></mj-divider>

            <mj-text font-size="20px" color="#F45e46" font-family="helvetica">
              Hello <a href="https://mjml.io" class="link-nostyle">World</a>
            </mj-text>

          </mj-column>
        </mj-section>
      </mj-container>
    </mj-body>
  </mjml>

sexy

attribute unit description default value
inline string set to “inline” to inline styles n/a

mjml-font

This tag allows you to import fonts if used in your MJML document

 <mjml>
   <mj-head>
     <mj-font name="Raleway" href="https://fonts.googleapis.com/css?family=Raleway" />
   </mj-head>
   <mj-body>
     <mj-container>
       <mj-section>
         <mj-column>
           <mj-text font-family="Raleway, Arial">
             Hello World!
           </mj-text>
         </mj-column>
       </mj-section>
     </mj-container>
   </mj-body>
 </mjml>

sexy

attribute unit description default value
href string url of the font n/a
name string name of the font n/a

mjml-title

This tag allows you to set the title of an MJML document

 <mjml>
   <mj-head>
     <mj-title>Hello MJML</mj-title>
   </mj-head>
   <mj-body>
     <mj-container>
       <mj-section>
         <mj-column>
           <mj-text>
             Hello World!
           </mj-text>
         </mj-column>
       </mj-section>
     </mj-container>
   </mj-body>
 </mjml>

sexy

Standard Body components

MJML comes out of the box with a set of standard components to help you build easily your first templates without having to reinvent the wheel.

mjml-container

This is the starting point of your email.

<mjml>
  <mj-body>
    <mj-container>
      <!-- Your email goes here -->
    </mj-container>
  </mj-body>
</mjml>

sexy

attribute unit description default value
css-class string HTML Element Class Name n/a
width px email’s width 600px
background-color color formats the general background color n/a

mjml-wrapper

wrapper

Wrapper enables to wrap multiple sections together. It’s especially useful to achieve nested layouts with shared border or background images across sections.

<mjml>
  <mj-body>
    <mj-container>
      <mj-section></mj-section>
      <mj-wrapper border="1px solid #000000" padding="50px 30px">
        <mj-section border-top="1px solid #aaaaaa" border-left="1px solid #aaaaaa" border-right="1px solid #aaaaaa" padding="20px">
          <mj-column>
            <mj-image padding="0" src="https://placeholdit.imgix.net/~text?&w=350&h=150" />
          </mj-column>
        </mj-section>
        <mj-section border-left="1px solid #aaaaaa" border-right="1px solid #aaaaaa" padding="20px" border-bottom="1px solid #aaaaaa">
          <mj-column border="1px solid #dddddd">
            <mj-text padding="20px"> First line of text </mj-text>
           <mj-divider border-width="1px" border-style="dashed" border-color="lightgrey" padding="0 20px" />
            <mj-text padding="20px"> Second line of text </mj-text>
          </mj-column>
        </mj-section>
      </mj-wrapper>
    </mj-container>
  </mj-body>
</mjml>

sexy

The full-width property will be used to manage the background width. By default, it will be 600px. With the full-width property on, it will be changed to 100%.

attribute unit description default value
full-width string make the wrapper full-width n/a
border string css border format none
border-bottom string css border format n/a
border-left string css border format n/a
border-right string css border format n/a
border-top string css border format n/a
border-radius px border radius n/a
background-color color section color n/a
background-url url background url n/a
background-repeat string css background repeat repeat
background-size percent/px css background size auto
vertical-align string css vertical-align top
text-align string css text-align center
padding px supports up to 4 parameters 20px 0
padding-top px section top offset n/a
padding-bottom px section bottom offset n/a
padding-left px section left offset n/a
padding-right px section right offset n/a

mjml-section

Sections are intended to be used as rows within your email. They will be used to structure the layout.

<mjml>
  <mj-body>
    <mj-container>
      <mj-section full-width="full-width" background-color="red">
        <!-- Your columns go here -->
      </mj-section>
    </mj-container>   
  </mj-body>
</mjml>

sexy

The full-width property will be used to manage the background width. By default, it will be 600px. With the full-width property on, it will be changed to 100%.

attribute unit description default value
full-width string make the section full-width n/a
border string css border format none
border-bottom string css border format n/a
border-left string css border format n/a
border-right string css border format n/a
border-top string css border format n/a
border-radius px border radius n/a
background-color color section color n/a
background-url url background url n/a
background-repeat string css background repeat repeat
background-size percent/px css background size auto
vertical-align string css vertical-align top
text-align string css text-align center
padding px supports up to 4 parameters 20px 0
padding-top px section top offset n/a
padding-bottom px section bottom offset n/a
padding-left px section left offset n/a
padding-right px section right offset n/a
direction string ltr / rtl ltr
css-class string HTML Element Class Name n/a

mjml-column

Columns enable you to horizontally organize the content within your sections. They must be located under mj-section tags in order to be considered by the engine. To be responsive, columns are expressed in terms of percentage.

Every single column has to contain something because they are responsive containers, and will be vertically stacked on a mobile view. Any standard component, or component that you have defined and registered, can be placed within a column – except mj-column or mj-section elements.

<mjml>
  <mj-body>
    <mj-container>
      <mj-section>
        <mj-column>
          <!-- Your first column -->
        </mj-column>
        <mj-column>
          <!-- Your second column -->
        </mj-column>
      </mj-section>
    </mj-container>
  </mj-body>
</mjml>

sexy

attribute unit description default attributes
background-color string background color for a column n/a
border string css border format none
border-bottom string css border format n/a
border-left string css border format n/a
border-right string css border format n/a
border-top string css border format n/a
border-radius px border radius n/a
width percent/px column width (100 / number of columns in section)%
vertical-align string middle/top/bottom top
css-class string HTML Element Class Name n/a

mjml-group

Desktop

Mobile

mj-group allows you to prevent columns from stacking on mobile. To do so, wrap the columns inside a mj-group tag, so they’ll stay side by side on mobile.

<mjml>
  <mj-body>
    <mj-container>
      <mj-section>
        <mj-group>
          <mj-column>
            <mj-image width="137px" height="185px" padding="0" src="https://mjml.io/assets/img/easy-and-quick.png" />
            <mj-text align="center">
              <h2>Easy and quick</h2>
              <p>Write less code, save time and code more efficiently with MJML’s semantic syntax.</p>
            </mj-text>
          </mj-column>
          <mj-column>
            <mj-image width="166px" height="185px" padding="0" src="https://mjml.io/assets/img/responsive.png" />
            <mj-text align="center">
              <h2>Responsive</h2>
              <p>MJML is responsive by design on most-popular email clients, even Outlook.</p>
            </mj-text>
          </mj-column>
        </mj-group>
      </mj-section>
    </mj-container>
  </mj-body>
</mjml>

sexy

attribute unit description default attributes
width percent/px group width (100 / number of sibling in section)%
vertical-align string middle/top/bottom top
background-color string background color for a group n/a

mjml-button

desktop

Displays a customizable button.

<mjml>
  <mj-body>
    <mj-container>
      <mj-section>
        <mj-column>
          <mj-button font-family="Helvetica" background-color="#f45e43" color="white">
            Don't click me!
          </mj-button>
        </mj-column>
      </mj-section>
    </mj-container>
  </mj-body>
</mjml>

sexy

attribute unit description default value
background-color color button background-color #414141
container-background-color color button container background color n/a
border string css border format none
border-bottom string css border format n/a
border-left string css border format n/a
border-right string css border format n/a
border-top string css border format n/a
border-radius px border radius 3px
font-style string normal/italic/oblique n/a
font-size px text size 13px
font-weight number text thickness bold
font-family string font name Ubuntu, Helvetica, Arial, sans-serif
color color text color #ffffff
text-decoration string underline/overline/none none
text-transform string capitalize/uppercase/lowercase none
align string horizontal alignment center
vertical-align string vertical alignment middle
href link link to be triggered when the button is clicked n/a
rel string specify the rel attribute for the button link n/a
inner-padding px inner button padding 15px 25px
padding px supports up to 4 parameters 15px 25px
padding-top px top offset n/a
padding-bottom px bottom offset n/a
padding-left px left offset n/a
padding-right px right offset n/a
width px button width n/a
height px button height n/a

mjml-text

This tag allows you to display text in your email.

<mjml>
  <mj-body>
    <mj-container>
      <mj-section>
        <mj-column>
          <mj-text>
            <h1>
              Hey Title!
            </h1>
          </mj-text>
        </mj-column>
      </mj-section>
    </mj-container>
  </mj-body>
</mjml>

sexy

attribute unit description default value
color color text color #000000
font-family string font Ubuntu, Helvetica, Arial, sans-serif
font-size px text size 13px
font-style string normal/italic/oblique n/a
font-weight number text thickness n/a
line-height px space between the lines 22px
letter-spacing px letter spacing none
height px The height of the element n/a
text-decoration string underline/overline/line-through/none n/a
text-transform string uppercase/lowercase/capitalize n/a
align string left/right/center left
container-background-color color inner element background color n/a
padding px supports up to 4 parameters 10px 25px
padding-top px top offset n/a
padding-bottom px bottom offset n/a
padding-left px left offset n/a
padding-right px right offset n/a
css-class string HTML Element Class Name n/a

mjml-image

Displays a responsive image in your email. It is similar to the HTML <img /> tag. Note that if no width is provided, the image will use the parent column width.

<mjml>
  <mj-body>
    <mj-container>
      <mj-section>
        <mj-column>
          <mj-image width="300" src="http://www.online-image-editor.com//styles/2014/images/example_image.png" />
        </mj-column>
      </mj-section>
    </mj-container>
  </mj-body>
</mjml>

sexy

attribute unit description default value
padding px supports up to 4 parameters 10px 25px
padding-top px top offset n/a
padding-bottom px bottom offset n/a
padding-left px left offset n/a
padding-right px right offset n/a
container-background-color color inner element background color n/a
border string css border definition none
border-radius px border radius n/a
width px image width 100%
height px image height auto
src url image source n/a
href url link to redirect to on click n/a
rel string specify the rel attribute n/a
alt string image description n/a
align position image alignment center
title string tooltip & accessibility n/a
css-class string HTML Element Class Name n/a

mjml-social

desktop

Displays calls-to-action for various social networks with their associated logo. You can activate/deactivate any icon, with display property.

<mjml>
  <mj-body>
    <mj-container>
      <mj-section>
        <mj-column>
          <mj-social
            mode="vertical"
            display="google facebook"
            google-icon-color="#424242"
            facebook-icon-color="#424242"
            facebook-href="My facebook page"
            google-href="My google+ page" />
        </mj-column>
      </mj-section>
    </mj-container>
  </mj-body>
</mjml>

sexy

attribute unit description default value
border-radius px border radius 3px
facebook-content string button text content Share
facebook-href url button redirection url [[SHORT_PERMALINK]]
facebook-rel string specify the rel attribute n/a
facebook-icon-color color icon color #3b5998
font-family string font name Ubuntu, Helvetica, Arial, sans-serif
font-size px/em font size 13px
google-content string button text content +1
google-href url button redirection url [[SHORT_PERMALINK]]
google-rel string specify the rel attribute n/a
google-icon-color color icon color #dc4e41
icon-size percent/px icon size 20px
instagram-content string button text content Share
instagram-href url button redirection url [[SHORT_PERMALINK]]
instagram-rel string specify the rel attribute n/a
instagram-icon-color color icon color #3f729b
line-height percent/px space between lines 22px
linkedin-content string button text content Share
linkedin-href url button redirection url [[SHORT_PERMALINK]]
linkedin-rel string specify the rel attribute n/a
linkedin-icon-color color icon color #0077b5
mode string vertical/horizontal horizontal
pinterest-content string button text content Pin it
pinterest-href url button redirection url [[SHORT_PERMALINK]]
pinterest-rel string specify the rel attribute n/a
pinterest-icon-color color icon color #bd081c
text-decoration string underline/overline/none none
text-mode string display social network name true
twitter-content string button text content Tweet
twitter-href url button redirection url [[SHORT_PERMALINK]]
twitter-rel string specify the rel attribute n/a
twitter-icon-color color icon color #55acee
align string left/right/center center
color color text color #333333
base-url string icon base url https://www.mailjet.com/images/theme/v1/icons/ico-social/
display string List of social icons to display separated by a space, facebook twitter google
available values: facebook google instagram pinterest linkedin twitter
inner-padding px social network surrounding padding 4px
padding px supports up to 4 parameters 10px 25px
padding-top px top offset n/a
padding-bottom px bottom offset n/a
padding-left px left offset n/a
padding-right px right offset n/a
container-background-color color inner element background color n/a

mjml-divider

Displays a horizontal divider that can be customized like a HTML border.

<mjml>
  <mj-body>
    <mj-container>
      <mj-section>
        <mj-column>
          <mj-divider border-width="1px" border-style="dashed" border-color="lightgrey" />
        </mj-column>
      </mj-section>
    </mj-container>
  </mj-body>
</mjml>

sexy

attribute unit description default value
border-color color divider color #000000
border-style string dashed/dotted/solid solid
border-width px divider’s border width 4px
width px/percent divider width 100%
container-background-color color inner element background color n/a
padding px supports up to 4 parameters 10px 25px
padding-top px top offset n/a
padding-bottom px bottom offset n/a
padding-left px left offset n/a
padding-right px right offset n/a

mjml-spacer

Displays a blank space.

<mjml>
  <mj-body>
    <mj-container>
      <mj-section>
        <mj-column>
          <mj-text>A first line of text</mj-text>
          <mj-spacer height="50px" />
          <mj-text>A second line of text</mj-text>
        </mj-column>
      </mj-section>
    </mj-container>
  </mj-body>
</mjml>

sexy

attribute unit description default value
height px spacer height 20px

mjml-table

This tag allows you to display table and filled it with data. It only accepts plain HTML.

<mjml>
  <mj-body>
    <mj-container>
      <mj-section>
        <mj-column>
          <mj-table>
            <tr style="border-bottom:1px solid #ecedee;text-align:left;padding:15px 0;">
              <th style="padding: 0 15px 0 0;">Year</th>
              <th style="padding: 0 15px;">Language</th>
              <th style="padding: 0 0 0 15px;">Inspired from</th>
            </tr>
            <tr>
              <td style="padding: 0 15px 0 0;">1995</td>
              <td style="padding: 0 15px;">PHP</td>
              <td style="padding: 0 0 0 15px;">C, Shell Unix</td>
            </tr>
            <tr>
              <td style="padding: 0 15px 0 0;">1995</td>
              <td style="padding: 0 15px;">JavaScript</td>
              <td style="padding: 0 0 0 15px;">Scheme, Self</td>
            </tr>
          </mj-table>
        </mj-column>
      </mj-section>
    </mj-container>
  </mj-body>
</mjml>

sexy

attribute unit description default value
color color text header & footer color #000
cellpadding pixels space between cells n/a
cellspacing pixels space between cell and border n/a
font-family string font name Ubuntu, Helvetica, Arial, sans-serif
font-size px/em font size 13px
line-height percent/px space between lines 22px
container-background-color color inner element background color n/a
padding px supports up to 4 parameters 10px 25px
padding-top px top offset n/a
padding-bottom px bottom offset n/a
padding-left px left offset n/a
padding-right px right offset n/a
width percent/px table width 100%
table-layout auto/fixed/initial/inherit sets the table layout. auto

mjml-raw

Displays raw HTML that is not going to be parsed by the MJML engine. Anything left inside this tag should be raw, responsive HTML.

<mjml>
  <mj-body>
    <mj-container>
      <mj-raw>
        <!-- Your content goes here -->
      </mj-raw>
    </mj-container>
  </mj-body>
</mjml>

sexy

mjml-accordion

accordion

mjml-accordion is an interactive MJML component to stack content in tabs, so the information is collapsed and only the titles are visible. Readers can interact by clicking on the tabs to reveal the content, providing a great experience on mobile devices where space is scarce.

<mjml>
  <mj-head>
    <mj-attributes>
      <mj-accordion border="none" padding="1px" />
      <mj-accordion-element icon-wrapped-url="http://i.imgur.com/Xvw0vjq.png" icon-unwrapped-url="http://i.imgur.com/KKHenWa.png" icon-height="24px" icon-width="24px" />
      <mj-accordion-title font-family="Roboto, Open Sans, Helvetica, Arial, sans-serif" background-color="#fff" color="#031017" padding="15px" font-size="18px" />
      <mj-accordion-text font-family="Open Sans, Helvetica, Arial, sans-serif" background-color="#fafafa" padding="15px" color="#505050" font-size="14px" />
    </mj-attributes>
  </mj-head>

  <mj-body>
    <mj-container background-color="#f5f5f5" width="650px">
        <mj-section padding="20px" background-color="#ffffff">
          <mj-column background-color="#dededd">
            <mj-accordion>
              <mj-accordion-element>
                <mj-accordion-title>Why use an accordion?</mj-accordion-title>
                <mj-accordion-text>
                  <span style="line-height:20px">Because emails with a lot of content are most of the time a very bad experience on mobile, mj-accordion comes handy when you want to deliver a lot of information in a concise way.
                  </span>
                </mj-accordion-text>
              </mj-accordion-element>
              <mj-accordion-element>
                <mj-accordion-title>How it works</mj-accordion-title>
                <mj-accordion-text>
                  <span style="line-height:20px">
                Content is stacked into tabs and users can expand them at will. If responsive styles are not supported (mostly on desktop clients), tabs are then expanded and your content is readable at once.</span>
                </mj-accordion-text>
              </mj-accordion-element>
            </mj-accordion>
          </mj-column>
        </mj-section>
    </mj-container>
  </mj-body>
</mjml>

sexy

attribute unit description default value
container-background-color n/a background-color of the cell n/a,
border n/a border n/a
font-family n/a font Ubuntu, Helvetica, Arial, sans-serif
icon-align n/a icon alignment middle
icon-wrapped-url n/a icon when accordion is wrapped http://i.imgur.com/bIXv1bk.png
icon-wrapped-alt n/a alt text when accordion is wrapped +
icon-unwrapped-url n/a icon when accordion is unwrapped http://i.imgur.com/w4uTygT.png
icon-unwrapped-alt n/a alt text when accordion is unwrapped -
icon-position n/a display icon left or right right
icon-height px icon width 32px
icon-width px icon height 32px
padding-bottom px padding bottom n/a
padding-left px padding left n/a
padding-right px padding right n/a
padding-top px padding top n/a
padding px padding 10px 25px

mjml-accordion-element

This component enables you to create a accordion pane

attribute unit description default value
background-color n/a background color n/a
font-family n/a font Ubuntu, Helvetica, Arial, sans-serif
icon-align n/a icon alignment middle
icon-wrapped-url n/a icon when accordion is wrapped http://i.imgur.com/bIXv1bk.png
icon-wrapped-alt n/a alt text when accordion is wrapped +
icon-unwrapped-url n/a icon when accordion is unwrapped http://i.imgur.com/w4uTygT.png
icon-unwrapped-alt n/a alt text when accordion is unwrapped -
icon-position n/a display icon left or right right
icon-height n/a icon width 32px
icon-width n/a icon height 32px

mjml-accordion-title

This component enables you to add and style a title to your accordion

attribute unit description default value
background-color n/a background color n/a
color n/a text color n/a
font-family n/a font family Ubuntu, Helvetica, Arial, sans-serif
font-size px font size 13px
padding-bottom px padding bottom n/a
padding-left px padding left n/a
padding-right px padding right n/a
padding-top px padding top n/a
padding px padding 16px

mjml-accordion-text

This component enables you to add and style a text to your accordion

attribute unit description default value
background-color n/a background color n/a
color n/a text color n/a
font-family n/a font family Ubuntu, Helvetica, Arial, sans-serif
font-size px font size 13px
padding-bottom px padding bottom n/a
padding-left px padding left n/a
padding-right px padding right n/a
padding-top px padding top n/a
padding px padding 16px

desktop

mjml-carousel is the first MJML interactive component, it displays a gallery of images or “carousel”. Readers can interact by hovering and clicking on thumbnails depending on the email client they use.

This component enables you to set the styles of the carousel elements.

<mjml>
  <mj-body>
    <mj-container>
      <mj-section>
        <mj-column>
          <mj-carousel>
            <mj-carousel-image src="https://www.mailjet.com/wp-content/uploads/2016/11/ecommerce-guide.jpg" />
            <mj-carousel-image src="https://www.mailjet.com/wp-content/uploads/2016/09/3@1x.png" />
            <mj-carousel-image src="https://www.mailjet.com/wp-content/uploads/2016/09/1@1x.png" />
          </mj-carousel>
        </mj-column>
      </mj-section>
    </mj-container>
  </mj-body>
</mjml>

sexy

attribute unit description default value
align string horizontal alignment center
border-radius px border radius n/a
background-color string column background color none
thumbnails String display or not the thumbnails (visible hidden)
tb-border css border format border of the thumbnails none
tb-border-radius px border-radius of the thumbnails none
tb-hover-border-color string css border color of the hovered thumbnail none
tb-selected-border-color string css border color of the selected thumbnail none
tb-width px thumbnail width null
left-icon url icon on the left of the main image https://mjml.io/assets/img/left-arrow.png
right-icon url icon on the right of the main image https://mjml.io/assets/img/right-arrow.png
icon-width px width of the icons on left and right of the main image 44px

This component enables you to add and style the images in the carousel.

attribute unit description default value
src url image source n/a
thumbnails-src url image source to have a thumbnail different than the image it’s linked to null
href url link to redirect to on click n/a
rel string specify the rel attribute n/a
alt string image description n/a
title string tooltip & accessibility n/a

mjml-navbar

Displays a menu for navigation with an optional hamburger mode for mobile devices.

<mjml>
  <mj-body>
    <mj-container>
      <mj-navbar background-color="#ef6451">
        <mj-column width="20%">
          <mj-image width="150px" src="https://mjml.io/assets/img/logo-white-small.png"></mj-image>
        </mj-column>
        <mj-column width="80%">
          <mj-inline-links base-url="https://mjml.io" hamburger="hamburger" ico-color="#ffffff">
            <mj-link href="/gettings-started-onboard" color="#ffffff">Getting started</mj-link>
            <mj-link href="/try-it-live" color="#ffffff">Try it live</mj-link>
            <mj-link href="/templates" color="#ffffff">Templates</mj-link>
            <mj-link href="/components" color="#ffffff">Components</mj-link>
          </mj-inline-links>
        </mj-column>
      </mj-navbar>
    </mj-container>
  </mj-body>
</mjml>

sexy

attribute unit description default value
full-width string make the section full-width n/a
border string css border format none
border-bottom string css border format n/a
border-left string css border format n/a
border-right string css border format n/a
border-top string css border format n/a
border-radius px border radius n/a
background-color color section color n/a
background-url url background url n/a
background-repeat string css background repeat repeat
background-size percent/px css background size auto
vertical-align string css vertical-align top
text-align string css text-align center
padding px supports up to 4 parameters 10px 25px
padding-top px section top offset n/a
padding-bottom px section bottom offset n/a
padding-left px section left offset n/a
padding-right px section right offset n/a

Individual links of the menu should we wrapped inside mj-inline-links.

Standard Desktop:

Standard Mobile:

Mode hamburger enabled:

attribute unit description default value
base url string base url for children components n/a
hamburger string activate the hamburger navigation on mobile if the value is hamburger n/a
align string align content left/center/right center
ico-open ASCII code decimal char code for a custom open icon (hamburger mode required) 9776
ico-close ASCII code decimal char code for a custom close icon (hamburger mode required) 8855
ico-padding px hamburger icon padding, supports up to 4 parameters (hamburger mode required) 10px
ico-padding-top px hamburger icon top offset (hamburger mode required) 10px
ico-padding-right px hamburger icon right offset (hamburger mode required) 10px
ico-padding-bottom px hamburger icon bottom offset (hamburger mode required) 10px
ico-padding-left px hamburger icon left offset (hamburger mode required) 10px
ico-align string hamburger icon alignment, left/center/right (hamburger mode required) center
ico-color color format hamburger icon color (hamburger mode required) #000000
ico-font-size px hamburger icon size (hamburger mode required) 30px
ico-font-family string hamburger icon font (only on hamburger mode) Ubuntu, Helvetica, Arial, sans-serif
ico-text-transform string hamburger icon text transformation none/capitalize/uppercase/lowercase (hamburger mode required) none
ico-text-decoration string hamburger icon text decoration none/underline/overline/line-through (hamburger mode required) none
ico-line-height px hamburger icon line height (hamburger mode required) 30px

This component should be used to display an individual link in the navbar.

attribute unit description default value
color color text color #000000
font-family string font Ubuntu, Helvetica, Arial, sans-serif
font-size px text size 13px
font-style string normal/italic/oblique n/a
font-weight number text thickness n/a
line-height px space between the lines 22px
text-decoration string underline/overline/none n/a
text-transform string capitalize/uppercase/lowercase/none uppercase
padding px supports up to 4 parameters 10px 25px
padding-top px top offset n/a
padding-bottom px bottom offset n/a
padding-left px left offset n/a
padding-right px right offset n/a
rel string specify the rel attribute n/a

mjml-hero

Display a section with a background image and some content inside (mj-text, mj-button, mj-image …) wrapped in mj-hero-content component

Fixed height

<mjml>
  <mj-body>
    <mj-container>
      <mj-hero
        mode="fixed-height"
        height="469px"
        background-width="600px"
        background-height="469px"
        background-url="https://cloud.githubusercontent.com/assets/1830348/15354890/1442159a-1cf0-11e6-92b1-b861dadf1750.jpg"
        background-color="#2a3448"
        padding="100px 0px">
        <!-- To add content like mj-image, mj-text, mj-button ... use the mj-hero-content component -->
        <mj-hero-content width="100%">
          <mj-text
            padding="20px"
            color="#ffffff"
            font-family="Helvetica"
            align="center"
            font-size="45"
            line-height="45px"
            font-weight="900">
            GO TO SPACE
          </mj-text>
          <mj-button href="https://mjml.io/" align="center">
            ORDER YOUR TICKET NOW
          </mj-button>
        </mj-hero-content>
      </mj-hero>
    </mj-container>
  </mj-body>
</mjml>

sexy

Fluid height

<mjml>
  <mj-body>
    <mj-container>
      <mj-hero
        mode="fluid-height"
        background-width="600px"
        background-height="469px"
        background-url="https://cloud.githubusercontent.com/assets/1830348/15354890/1442159a-1cf0-11e6-92b1-b861dadf1750.jpg"
        background-color="#2a3448"
        padding="100px 0px">
        <!-- To add content like mj-image, mj-text, mj-button ... use the mj-hero-content component -->
        <mj-hero-content width="100%">
          <mj-text
          padding="20px"
          color="#ffffff"
          font-family="Helvetica"
          align="center"
          font-size="45"
          line-height="45px"
          font-weight="900">
            GO TO SPACE
          </mj-text>
          <mj-button href="https://mjml.io/" align="center">
            ORDER YOUR TICKET NOW
          </mj-button>
        </mj-hero-content>
      </mj-hero>
    </mj-container>
  </mj-body>
</mjml>

sexy

attribute unit description default value
width px hero container width parent element width
mode fluid-height/fixed-height choose if the height is fixed based on the height attribute or fluid fluid-height
height px hero section height (required for fixed-height mode) 0px
background-width px width of the image used 0px
background-height px height of the image used 0px
background-url url absolute background url n/a
background-color color hero background color #ffffff
background-position top/center/bottom left/center/right background image position center center
padding px supports up to 4 parameters 0px
padding-top px top offset 0px
padding-right px right offset 0px
padding-left px left offset 0px
padding-bottom px bottom offset 0px
vertical-align top/middle/bottom content vertical alignment top

mjml-hero-content

Display some content in an mj-hero component

attribute unit description default value
width px/percent content width 100%
align left/center/right horizontal alignment center
background-color color content background color transparent
padding px supports up to 4 parameters 0px
padding-top px top offset 0px
padding-right px right offset 0px
padding-left px left offset 0px
padding-bottom px bottom offset 0px

mjml-invoice

Display a table of items with calculated total price.

<mjml>
  <mj-body>
    <mj-container>
      <mj-section>
        <mj-column width="100%">
          <mj-invoice format="0,00.00€" intl="name:Product Name">
            <mj-invoice-item name="TV" price="549€" quantity="1" />
            <mj-invoice-item name="DVD - Iron Man II" price="22.99€" quantity="2" />
          </mj-invoice>
        </mj-column>
      </mj-section>
    </mj-container>
  </mj-body>
</mjml>

sexy

attribute unit description default value
align string left/center/right left
color color text header & footer color #b9b9b9
font-family string font name Roboto, Ubuntu, Helvetica, Arial, sans-serif
font-size px/em font size 13px
line-height percent/px space between lines 22px
border string border-bottom header & border-top footer 1px solid #ecedee
container-background-color color inner element background color n/a
padding px supports up to 4 parameters 10px 25px
padding-top px top offset n/a
padding-bottom px bottom offset n/a
padding-left px left offset n/a
padding-right px right offset n/a
intl string formatted string to set wording for header and footer “name:Name;quantity:Quantity;price:Price”
format string how to format total price, based on numeraljs n/a

mjml-invoice-item

Display a row in an mj-invoice component

<mjml>
  <mj-body>
    <mj-container>
      <mj-section>
        <mj-column>
          <mj-invoice format="0,00.00€" intl="name:Product Name">
            <mj-invoice-item name="TV" price="549€" quantity="1" />
            <mj-invoice-item name="DVD - Iron Man II" price="22.99€" quantity="2" />
          </mj-invoice>
        </mj-column>
      </mj-section>
    </mj-container>
  </mj-body>
</mjml>
attribute unit description default value
color color text color #747474
font-family string font name Roboto, Ubuntu, Helvetica, Arial, sans-serif
font-size px/em font size 14px
line-height percent/px space between lines 22px
border string border-bottom header & border-top footer 1px solid #ecedee
text-align string css text align left (quantity column: right)
padding px supports up to 4 parameters 10px 25px
padding-top px top offset n/a
padding-bottom px bottom offset n/a
padding-left px left offset n/a
padding-right px right offset n/a
name string item name n/a
price string/number price (should already be formatted) 0
quantity number quantity 0

mjml-location

Display a Google Maps location link

<mjml>
  <mj-body>
    <mj-container>
      <mj-section>
        <mj-column>
          <mj-location address="37 bis, rue du Sentier 75002 Paris" />
        </mj-column>
      </mj-section>
    </mj-container>
  </mj-body>
</mjml>

sexy

attribute unit description default value
color color text color #3aa7ed
font-family string font name Roboto, sans-serif
font-size px/em font size 18px
font-weight css weight font weight 500
href string href link on image/text http://maps.google.com/maps?q=(mjAttribute: address)
rel string specify the rel attribute n/a
padding px supports up to 4 parameters 10px 25px
padding-top px top offset n/a
padding-bottom px bottom offset n/a
padding-left px left offset n/a
padding-right px right offset n/a
img-src string image source http://i.imgur.com/DPCJHhy.png

Community components

In addition to the standard components available in MJML, our awesome community is contributing by creating their own components.

To use a community component, proceed as follows: - Install MJML locally with npm install mjml in a folder - Install the community component with npm install {component-name} in the same folder - Create a .mjmlconfig file in the same folder with:

{
  "packages": [
    "./node_modules/component-name/path-to-js-file"
  ]
}

Finally, you can now use the component in a MJML file, for example index.mjml, and run MJML locally in your terminal (make sure to be in the folder where you installed MJML and the community component): ./node_modules/.bin/mjml index.mjml.

mjml-chart

Thanks to image-charts for their contribution with this component. It’s available on Github and NPM.

mjml-charts

Displays charts as images in your email.

Validating MJML

MJML provides a validation layer that helps you building your email. It can detect if you misplaced or mispelled a MJML component, or if you used any unauthorised attribute on a specific component. It supports 3 levels of validation: * skip: your document is rendered without going through validation * soft: your document is going through validation and is rendered, even if it has errors * strict: your document is going through validation and is not rendered if it has any error

By default, the level is set to soft.

In CLI

When using the mjml command line, you can add the option -l or --level with the validation level you want.

Validates the file without rendering it

$> mjml --validate template.mjml

Sets the validation level to skip (so that the file is not validated) and renders the file

$> mjml -l skip -r template.mjml

In Javascript

In Javascript, you can provide the level through the options parameters on MJMLRenderer. Ex: new MJMLRenderer(inputMJML, { level: strict })

strict will raise a MJMLValidationError exception. This object has 2 methods: - getErrors returns an array of objects with line, message, tagName as well as a formattedMessage which contains the line, message and tagName concatenated in a sentence. - getMessages returns an array of formattedMessage.

When using soft, no exception will be raised. You can get the errors using the object returned by the render method errors. It is the same object returned by getErrors on strict mode.

Use of .mjmlconfig file

If not exists, add a .mjmlconfig file at the root of your project (where you execute the mjml command). Add the following key to the json: { … “validators”: [ “validateTag”,
“validateAttribute”, “validChildren”, “./validators/ColumnCount.js”, ] }

“validateTag”, “validateAttribute” and “validChildren” are the default validation rules. If you want to add custom rules, you can add the path to the file where the validtion function resides.

Creating a Component

One of the great advantages of MJML is that it’s component based. Components abstract complex patterns and can easily be reused. Added to the standard library of components, it is also possible to create your own components!

To learn how to create your own component, follow this step-by-step guide which also includes a ready-to-use boilerplate.

Using MJML in JSON

MJML can not only be used as a markup, but also as a JSON object, which can be very useful for programmatic manipulation or with the MJML API.

With the JSON format, a MJML component is defined as an object with the following properties:

Exactly like using MJML as a markup, the JSON definition can be passed as an object to mjml.mjml2html(). Here is working example:

var mjml = require('mjml')

console.log(mjml.mjml2html({
  tagName: 'mjml',
  attributes: {},
  children: [{
    tagName: 'mj-body',
    attributes: {},
    children: [{
      tagName: 'mj-container',
      attributes: {},
      children: [{
        tagName: 'mj-section',
        attributes: {},
        children: [{
          tagName: 'mj-column',
          attributes: {},
          children: [{
              tagName: 'mj-image',
              attributes: {
              'width': '100px',
              'src': '/assets/img/logo-small.png'
              }
            },
            {
              tagName: 'mj-divider',
              attributes: {
                'border-color' : '#F46E43'
              }
            }, 
            {
            tagName: 'mj-text',
            attributes: {
              'font-size': '20px',
              'color': '#F45E43',
              'font-family': 'Helvetica'
            },
            content: 'Hello World'
          }]
        }]
      }]
    }]
  }]
}))

Tooling

In order to provide you with the best experience with MJML and help you use it more efficiently, we’ve developed some tools to integrate it seamlessly in your development workflow:

Atom language plugin

Atom is a powerful text editor originally released by Github. This package provides autocompletion and syntax highlighting for MJML. It is available on Github and through the Atom Package Manager (APM).

Atom linter

In addition to the language package, a linter is available to highlight errors in MJML. The linter is available on Github and through the Atom Package Manager (APM).

Atom preview

The Atom preview package enables you to see how your email renders as you code, directly within Atom. The preview package is available on Github and through the Atom Package Manager (APM).

Sublime Text

Sublime Text is a powerful text editor. We’re providing you with a package to color MJML tags. It is available on Github and through the Sublime Package Control.

Gulp

Gulp is a tool designed to help you automate and enhance your workflow. Our plugin enables you to plug the MJML translation engine into your workflow, helping you to streamline your development workflow. It is available here on Github

Contribute to the MJML ecosystem

The MJML ecosystem is still young and we’re also counting on your help to help us make it grow and provide its community with even more awesome tools, always aiming to making development with MJML an efficient and fun process!

Getting involved is really easy and our roadmap is open. If you want to contribute, feel free to open an issue or submit a pull-request!