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>
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
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:
From here, you can first define your 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.
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:
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
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
<!-- 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
<!-- 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>
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>
| 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>
| 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>
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>
| 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 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>
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>
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>
| 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>
| 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
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>
| 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>
| 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>
| 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
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>
| 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>
| 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>
| 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>
| 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>
mjml-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>
| 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 |
mjml-carousel
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>
| 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 |
mjml-carousel-image
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>
| 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 |
mjml-inline-links
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 |
mjml-link
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>
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>
| 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>
| 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>
| 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.
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:
- a
tagNameas astring - a list of attributes as an
object - either a
contentas astringor a list ofchildrentags as anarray.
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!