Coding Responsive Emails with MJML’s desktop app (for non-developers and developers) — Part I

How to set up and use MJML’s desktop app to create snippets and make basic email templates

7 min readNov 21, 2018

Creating emails from scratch is a hell of a task… Luckily there’s MJML to save the day. With MJML components you can save yourself hours of sweat and tears cos the Mailjet team’s already done the hard work for you. MJML components are simple enough that even non-devs can learn to use them. The team’s even put out a desktop app (for Mac only) and an online editor, so there are plenty of options for everyone.

Here’s a little two-part tutorial to get you started with the desktop app. We’ll be building a basic email template. This is for non-developers who don’t mind doing a little bit of coding — it’s practically like writing English! (I’ll do a separate article for developers that will go in a little deeper into using the CLI and a text editor later.)

Note: This tutorial is written with MJML version 4.1.2. The latest release at the time of this tutorial is v4.2.0-beta.2

Here’s what we’re going to build:

Check out the full code here: https://mjml.io/try-it-live/HkVE0pGY7

WHAT WE’LL COVER (PART I)

How to set up and use the MJML desktop app
How to set up a basic email template from scratch with MJML
How to create a snippet in the MJML desktop app

WHAT WE’LL COVER (PART II)

How to put together an email with the following pieces: Header, Hero Image + CTA, Body Copy, Image + Subtext, Footer
How to compile MJML into HTML

PREREQUISITES

None. Nice-to-haves are HTML and CSS. A little JS if you want to eventually build your own MJML components…

Setting up and using MJML

Go download the desktop app!
Once you’ve done that and opened it up, click “New project” in the upper-right corner of the app. It’ll open up a little box where you should input the name of your project. You can ignore the location input unless you have a specific place you want to save your file. Once you’ve typed in your project name, click “Choose template”.
The next modal screen should show you two main tabs — “Basic” and “Gallery”. “Basic” is the default and gives you two options: a single file, basic layout or a layout with a header and footer already included. Feel free to click on “Gallery” if you just want to explore MJML’s default templates, but since we’re here to build something from scratch, we’re going to go ahead and click the “single file, basic layout” option. Click “create” when you’re ready to move on.
The modal box should go away at this point, leaving you with something like this, basic code included. We’re going to erase everything inside the editor (that’s the middle section with the all the default code in it).

Setting up a basic template from scratch

Now that we have a blank editor, we’re going to create our own basic template like so:

<mjml owa="desktop">
    <mj-head>
        <mj-title>INSERT TITLE HERE</mj-title>
        
        <mj-font
            name="Montserrat"
            href="https://fonts.googleapis.com/css?family=Montserrat:400,600,800"
        />
        <mj-attributes>
            <mj-all
                padding="0px"
                font-family="Montserrat, Helvetica, sans-serif"
            />
        </mj-attributes>        <mj-preview>
            INSERT PREVIEW TEXT HERE
        </mj-preview>
    </mj-head>    <mj-body width="640px">
    <mj-raw><!-- ==***== Mj-Body ABOVE ==***== --> </mj-raw>        PUT COMPONENTS HERE    <mj-raw><!-- ==***== Mj-Body BELOW ==***== --></mj-raw>
    </mj-body>
</mjml>

Here’s a breakdown of what all of this means…

First of all, what is this even?

Anytime you see <mj-blah>, you are looking at what’s called an MJML tag. These are the basic building blocks of our email. Basically what this stuff ends up converting into later on is HTML and CSS, but as a non-dev you probably don’t care much about that do you so long as it works, right?

OK. Now anytime you see an <mj-blah>, just know that we also need to close it with another tag. This can happen in two ways.

Most of the time you close it with a slash like so: </mj-blah>

Very rarely will you see what’s known as a self-closing tag. In fact, off hand I can only thing of one: <mj-image />

MJML has a bunch of components which you can use via these magical tags. Each tag can have one or more “attributes”. For instance, <mj-font> can have an attribute called “name”, an attribute called “href”, etc. Each of these attributes can have values. So in our example above, <mj-font> has an attribute called “name” with a value of “Montserrat”. Using attributes, we set the colour and size of our text, the width of an image, etc.

Now for a breakdown of that giant blob of code…

Right at the top,<mjml owa="desktop"> is specifying which display to use on Outlook.com. If you don’t specify “desktop”, MJML’s default for Outlook.com is the mobile version of an email. Your call on which you would rather. Simply omit the owa="desktop and use a plain <mjml> tag if this you want the mobile view to be default.
Then we have a tag called <mj-head> . Anything that isn’t directly visible instead our final email design gets to sit here. You can read more on which components can be nested within it here. In our example, we’re using <mj-title> , <mj-font> , <mj-attributes> , <mj-all> and <mj-preview> .
<mj-title> allows you to add an email title. It takes no attributes.
<mj-font> takes two attributes: “href”, whose value is the url of the webfont you want to use (in our case, we’re linking using Montserrat, a Google font); “name”, which is the name of the font.
<mj-attributes> “allows you to modify default attributes on a mj-tag and add mj-class to them”. In our case, we only need it so that we can use <mj-all> which allows us to set “default attributes for every components inside your MJML document”.
As you can see, we’ve set every component of our document to have the following defaults: no padding (ie. don’t add add any default space around any of the elements), and a specific set of font families (Montserrat, Helvetica and sans-serif).
<mj-preview> takes no attributes. It simply allows us to set preview text for the email in question. (Find out what preview text is here).
Now that we’re done going through <mj-head> , the next bit of code in our template is contained within <mj-body> which we’ve given an attribute of “width” and a value of “640px”. This tag contains all the visible elements of your email, with the exception of anything that is found within <mj-raw> (more on that next).
You can set your email to have whatever max-width you want. 600px is a safe standard, but you can go as far as 640px without too much trouble.
<mj-raw> allows to write comments in normal human language within our code. This is totally optional, but very helpful in keeping your organized as you add more and more components. I like to signal the beginning and end of any major component using raw tags so that I don’t get lost.

How to create a snippet in the MJML desktop app

Now that we’ve put in all this hard work to create a basic template, you’ll likely want to reuse this pattern over and over again as you create new emails. There’s no sense in re-writing it every time. The MJML desktop app comes with a snippet helper so that you can store bits of code like this that you intend to reuse.

Select all the code in your editor and copy it.
Click the gear icon in the top-right corner of the window.
Click “<> Snippets” in the left-nav bar.
Give your snippet a name. I’d call this something along the lines of “Basic email shell” or whatever.
Give your snippet a trigger. This is basically a shortcut you type in the editor which will paste in the entire snippet of code. Let’s name this one “mjShell”. Don’t use underscores or special characters in the snippet trigger or it won’t work.
Paste in your code into the box under “Snippet Content” and click “Create Snippet”.
You can modify your snippet later by clicking the name of the snippet on the right.
Close the modal, which will take you back to the main editor.
Erase everything in the editor.
Type in mjShell then hit “tab”. Your template should reappear! Now every time you want to start a new email, all you have to do is open up a new doc and use your snippet to get you started.