How to code a responsive email ?

April 8, 2020

By Quentin Ferrer

Through this article, Quentin Ferrer, Consultant at ADNEOM in Luxembourg tells you how to code your first responsive email in 10 minutes only !

Imagine: You’ve just spent a lot of time creating an amazing email for your client, but when you send a test email in your mailbox, you see that it looks bad… No worries, Quentin has you covered !

Why emails are so hard to code ? 

There is a main reason why creating responsive emails is not an easy task: There is no standard in the way email clients render HTML. Each device and email client render HTML differently. The best solution is to use a framework that solves for you most of the quirks of email clients. It provides you with standards features such as grid system, typography, utility classes, buttons, images, and links. It also can handle responsive design very well and speed up your development time.

What is MJML ?

MJML is an open source framework (10.2k stars) created internally by Mailjet, a company specialized in email marketing tools. It provides features easy to use to reduce the pain of coding responsive email:

  • An easy syntax for making the language very easy to learn and understand. Say goodbye to endless HTML table nesting or email client CSS.
  • Standard components to be ready to create emails with your business logic. The navbar, accordion and carousel components help you to make interactive emails. A fallback is displayed for the email client which does not support interactions.
  • A full flexibility for developers who would like customize existing components or create their own.
  • A responsive-by-design on most-popular email clients, even Outlook. Use semantic tags that integrate the fallbacks and hacks needed to make an email responsive.

How does it works ?

MJML is built in React for using the power of React’s components. The component names are semantic, starting with mj-, so that they are simple and easy to recognize and understand.

The MJML basic structure is like a regular HTML template, it has a head (mj-head) and body (mj-body) tags.

Like most popular CSS framework, MJML based on a system of rows (mj-section) and columns (mj-column) to make the email responsive. Inside any section, there are one or more columns. Columns will appear side-by-side on desktop and stack on mobile by default. Sections cannot be nested into sections.

The default break point is equal to 480px, but the mj-breakpoint component allows you to change on which break point the layout should go desktop to mobile.

Coding in MJML

Before starting the tutorial, let’s get ready to code in MJML. There are different ways to use MJML, such as running it locally or using the online editor, the best solution if you don’t want to install anything for this tutorial.

Building your first email

In this section, you’re going to learn how to code a basic email template using MJML. For the example, I’m using the layout of the ADNEOM internal newsletter available on

Creating the document structure

First, create the MJML structure that looks like :

Setting the default attributes

As you can see in the template, there are things that look alike:

  • Most texts have the same font family, font size and color
  • The dividers never change
  • The button always has a background color in red and a text color in white.

For that, set a default style by using the head component mjml-attributes which allows you to modify default attributes on each MJML component:

For example, the default attributes will be set on each mj-text component inside the body. You can still manually override the attribute by specifying a new one directly on the component.

Adding content

Now you’re ready to add content to your email. As a reminder, MJML layouts are based on mj-section to create rows and mj-column to create columns inside rows.

You have to know that each section has the following default attributes:

  • The width is equal to 600px
  • The padding top and bottom are equal to 20px
  • The text is aligned in the center

And each column are expressed in terms of percentage (default 100% width) to be responsive.

Adding the header

The mj-image component helps you to insert image and make it responsive. It is similar to the HTML <img/> tag.

The image will use the width of the parent column because the width attribute is not specified.

Adding the title

The mj-text allow you to display text in your mail.

The default attributes for each text are:

  • The size is equal to 13px
  • The color is black (blue in your case with the default attributes defined in the head tag)
  • The padding top and bottom are equal to 10px
  • The padding left and right are equal to 25px

You have to overwrite the attributes to display the text in red, in bold with a size larger than default text

Adding the message

Now you know the component to display text, adding the message is easy for you.

As you can see, you are allowed to insert any HTML tag with any attributes inside the text component. Each paragraph is inserted inside a text component. It will be separated by the default padding top and bottom of the component. Of course, you can add the text inside a single text tag and use the HTML </br> tag for breaking the line

Adding the divider (start of articles)

The mj-divider displays a horizontal divider that can be customized like a HTML border.

The default attributes for the component are:

  • The color is black (red in your case with the default attributes defined in the head tag)
  • The border style is solid (dotted in your case with the default attributes defined in the head tag)
  • The border width is 4px
  • The padding top and bottom are equal to 10px
  • The padding left and right are equal to 25px
  • The width is equal to 100%

Add the divider component with no attributes in the body component:

Adding the block title

Use the mj-text component to add the block title in the red color, in bold, align in the center and a larger size:

Adding the article

The article has a two-column layout:

  • A column with the article image
  • A column with the article title, description and the button
  • Add the article image in the first column:
  • and add the article title, description and button in the second column:

Adding the divider (end of articles)

This section is easy to achieve by using the mj-divider component again

Adding the footer

The footer has a two-column layout like the article:

  • A column with the signature
  • A column with the logo and social networks of the company
  • Add the signature in the first column:
  • and add the logo and social networks of the company in the second column
  • Note that mj-social-element component is able to automatically displaying a supported social icon.
    Here, the component is customized because the style in the template is different from the MJML social icon style.

Rendering the HTML file

Using the online editor, nothing to do. You can download the HTML by clicking the « HTML » button on the top right part of the editor.

Using MJML in local, you have to use the MJML CLI.

You can see the result on the online editor:

What’s next ?

  • Test your HTML email in different email clients with a tool like Litmus or Email on Acid.
  • Send your mail with an email service provider or directly from you shell.
  • Integrate MJML in your projects by using package.json or MJML API and use your favorite mailer service to send the generated HTML.
  • Create your own component based on your business logic.


Quentin Ferrer, Consultant at ADNEOM in Luxembourg.

Categorised in:

This post was written by Marine Herve