Creating Responsive Newsletters with the MJML Email Framework

The process of coding email newsletters sucks! You are forced to use web 1.0 code and have to abide by various platform and device standards. It isn’t a pretty process and definitely a time consuming task, but thankfully, there are groups of programmers who put in a lot of time and effort to create email frameworks that take all of the pain points out of coding an email and make it simple for anyone to take an email from to design to product.

For their dedication to helping make everyone's lives easier, I decided to write a post on the topic of email coding using Product Hunt darling and responsive email framework, MJML. MJML is a new framework that has risen to fame for having an open-source semantic markup language that is much simpler than other responsive email frameworks on the market. The simplicity of this markup language is in its ability to remove the need for coding HTML tables and inline CSS code, yet still be able to convert code into HTML compliant code that works for all devices and platforms. The final product will impress anyone and everyone, and I’m still astounded by how easy it was to pick up and learn the framework. I could go on with praise, but I would rather have you be the judge of that yourself and build out a template with my steps below.

Prerequisites:

Node - Version 4.2.0 or Higher. At the time of this writing, 4.3.2 is the most mature and dependable version)

NPM - Comes with node installation

Text editor program - It doesn’t matter which you use, but MJML has syntax plugins for popular programs Sublime Text & Atom.io

Command Line Interface knowledge

HTML knowledge

Steps:

1. Create a folder to house our files and within your command line interface navigate to this folder. In my example, my folder is titled newsletter found within my Projects folder located on my desktop, so I use $ cd ~/Desktop/Projects/newsletter.

$ cd /user/path/to/folder

2. Install MJML from the command line with the following command

$ npm install mjml

If installed correctly, you should see a console log of the modules installed from your command line and a “node_modules” folder with an mjml folder inside.

3. Open your text editor and create a file called index.mjml. This file will contain our newsletter code. If you would like syntax highlighting for your mjml files and are using Sublime Text or Atom.io, then head to the developer site for the syntax plugins.

4. Back in your command line, run the following command,

$ mjml -w index.mjml -o index.html

to watch our index.mjml file. This process will auto-update the changes made in our code to the outputted html file.

If you do not want the outputted file to update with every change, then run

$ mjml -r index.mjml -o index.html 

whenever you want to output your changes to an html file.

Regardless of the command that is used, you will see an HTML file appear that will contain our converted mjml code that is ready to be shipped in an email.

5. Switch back to your text editor and set up sections for the individual parts of the newsletter. In my example, I have split the newsletter into four different sections marked by the <!-- --> comments tags. The section tags are the foundational elements of the MJML code and all additional code like columns and other HTML elements must be wrapped in section tags. In addition to setting up our sections, we will also apply attributes to each section. For a list of attributes that can be applied to the section tag, as well as other tags, consult the documentation found here: https://mjml.io/documentation/#mj-section

Note: Please disregard the whitespacing after the opening of the tag <. I'm currently looking into why this is happening :)


< mj-body>
  < !-- Logo -->
  < mj-section background-color="#fff">
  < /mj-section>
  < !-- Featured Article -->
  < mj-section background-color="#00a8df">
  < /mj-section>
  < !-- Additional articles -->
  < mj-section background-color="#fff">
  < /mj-section>
  < !-- Social Media Icons -->
  < mj-section background-color="#fff">
  < /mj-section>
< /mj-body>

6. In the first section of our newsletter, we will create a logo button that will direct users to our website. To do this, we must first add a column tag. Like many responsive frameworks, MJML works off a column grid system that currently supports up to four columns. There isn’t much detail on the four column limitation outside of saying that it is aesthetic purposes. This makes sense since email messages aren’t optimized for browser/website pixel sizes. For this section, we aren’t using that much copy so one mj-column will suffice, but we will explore multiple column usage in later sections. After adding a column, add a mj-button tag. This tag is a built-in component that creates a decorated link.



  < mj-section background-url="http://orig02.deviantart.net/6e1c/f/2014/020/c/4/martin_stavars_new_york12_by_xmegalopolisx-d72yha7.jpg" background-size="cover" background-repeat="no-repeat">
    < mj-column>
      < mj-button background-color="#00a8df" href="www.connordphillips.com">
          CONNOR PHILLIPS
      < /mj-button>
    < /mj-column>
  < /mj-section>

7. Moving on to our featured article section, we will use more built-in components like image and text tags. First, let's add an image for our featured article with the mj-image tag that will be prominently placed in the center of our newsletter. As you can see from our tag, the mj-image syntax isn’t much different from the standard <img> HTML tag. After our image tag, lets add mj-text tags for the title and article description. The same similarities that mj-image has with <img> can be said about <mj-text> and <p> tags. Finally, let’s add in a button that will link to this article.


< !-- Featured Article -->
  < mj-section background-color="#00a8df">
    < mj-column>
      < mj-image src="http://s3.amazonaws.com/ghost-blogpost-images/2016/Feb/marketers_web_scraping-1456097087068.png">< /mj-image>
      < mj-text color="#fff">Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
      tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
      quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
      consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
      cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
      proident, sunt in culpa qui officia deserunt mollit anim id est laborum.< /mj-text>
      < mj-button background-color="#fff" color="#00a8df" href="http://www.connordphillips.com/2016/02/22/introduction-to-web-scraping-for-marketers/">
        Read More
      < /mj-button>
    < /mj-column>
   < /mj-section>

8. Now that we have our featured article in place, let’s create a section that contains two columns for additional articles. Creating two columns is completely within the capacity of this framework, but as I mentioned before, MJML caps out at four columns. While this might seem like a deal breaker for some email designers and coders, I want to mention that you have the ability to overwrite the auto-sizing mechanism that comes with the four column, as well as have the ability to set custom pixel sizes for each column. I will not be using this type of customization in this tutorial, but I wanted to mention this to any readers who are quick to write off the framework because of this limitation.

To create both columns we simply add two, <mj-column></mj-column> tags. Within these tags we create identical mj-text and mj-button tags.


< !-- Additional Articles -->
  < mj-section background-color="#fff">
    < !-- Column One -->
    < mj-column>
      < mj-text color="#00a8df" font-size="20">Essential Content Marketing Metrics and Dimensions< /mj-text>
      < mj-text font-size="10">Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
      tempor incididunt ut labore et dolore magna aliqua.< /mj-text>
      < mj-button background-color="#00a8df" href="http://www.connordphillips.com/2016/02/04/essential-content-marketing-metrics-and-dimensions/">
        Read More
      < /mj-button>
    < /mj-column>
    < !-- Column Two -->
    < mj-column>
      < mj-text color="#00a8df" font-size="20">10 Excel Keyboard Shortcuts & Tricks for Marketers< /mj-text>
      < mj-text font-size="10">Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
      tempor incididunt ut labore et dolore magna aliqua.< /mj-text>
       < mj-button background-color="#00a8df" href="http://www.connordphillips.com/2016/02/24/10-excel-keyboard-shortcuts-tricks-for-marketers/">
        Read More
      < /mj-button>
    < /mj-column>
  < /mj-section>

9. Finally we will cap off this tutorial with social sharing buttons so that we can grow our newsletter audience by allowing readers to share with others. Typically social sharing lists in emails are built out by hard-coding image tags for each social network, but MJML has condensed this logic into a single tag that provides the ability to list our social networks by simply referencing the network in the attributes portion of the tag.As you can see from our code I added an <mj-social> tag with a display attribute that contains individual social media network names. This is all that is need to display each image and link. One thing to note is that this does not work for every social media network that you can think of. You are limited to what the mjml team has built-in, which is facebook google instagram pinterest linkedin twitter.


< !-- Social Share Icons -->
  < mj-section background-color="#00a8df">
    < mj-column>
      < mj-text align="center" color="#fff">Please share if you enjoyed!< /mj-text>
      < mj-social mode="vertical" display="twitter facebook" />
  < /mj-column>
    < /mj-column>
  < /mj-section>
< /mj-body>

And with the social share icon section built out, we are officially finished with our responsive newsletter. Give it a test run with your email marketing solution and make sure to test on every platform and device to make sure that there aren’t weird device/platform-specific bugs. MJML is built with HTML compliant code based on best practices, so you shouldn’t have any issues like I mentioned, but you should always play it safe and test.

Your final result should look like this:

Before you jump into the full code below, please note that I did not cover every component included in the framework, nor did I cover the ability to write raw code and create custom components. The purpose of this article was to get your toes wet with the new framework and show you the great job the mjml team has done in removing many of the frustrations that email coders face when going from design to product. If there is enough support from this tutorial, I will follow up with a piece on the more advanced customizations you can make. To voice your support, please share this tutorial on social media or sign up for my newsletter!

Full code located on Github and below

Full code:


< mj-body>
  < !-- Logo -->
  < mj-section background-url="http://orig02.deviantart.net/6e1c/f/2014/020/c/4/martin_stavars_new_york12_by_xmegalopolisx-d72yha7.jpg" background-size="cover" background-repeat="no-repeat">
    < mj-column>
      < mj-button background-color="#00a8df" href="www.connordphillips.com">
          CONNOR PHILLIPS
      < /mj-button>
    < /mj-column>
  < /mj-section>
  < !-- Featured Article -->
  < mj-section background-color="#00a8df">
    < mj-column>
      < mj-image src="http://s3.amazonaws.com/ghost-blogpost-images/2016/Feb/marketers_web_scraping-1456097087068.png">< /mj-image>
      < mj-text color="#fff">Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
      tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
      quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
      consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
      cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
      proident, sunt in culpa qui officia deserunt mollit anim id est laborum.< /mj-text>
      < mj-button background-color="#fff" color="#00a8df" href="http://www.connordphillips.com/2016/02/22/introduction-to-web-scraping-for-marketers/">
        Read More
      < /mj-button>
    < /mj-column>
   < /mj-section>
  < !-- Additional Articles -->
  < mj-section background-color="#fff">
    < !-- Column One -->
    < mj-column>
      < mj-text color="#00a8df" font-size="20">Essential Content Marketing Metrics and Dimensions< /mj-text>
      < mj-text font-size="10">Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
      tempor incididunt ut labore et dolore magna aliqua.< /mj-text>
      < mj-button background-color="#00a8df" href="http://www.connordphillips.com/2016/02/04/essential-content-marketing-metrics-and-dimensions/">
        Read More
      < /mj-button>
    < /mj-column>
    < !-- Column Two -->
    < mj-column>
      < mj-text color="#00a8df" font-size="20">10 Excel Keyboard Shortcuts & Tricks for Marketers
      < mj-text font-size="10">Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
      tempor incididunt ut labore et dolore magna aliqua.< /mj-text>
       < mj-button background-color="#00a8df" href="http://www.connordphillips.com/2016/02/24/10-excel-keyboard-shortcuts-tricks-for-marketers/">
        Read More
      < /mj-button>
    < /mj-column>
  < /mj-section>
  < !-- Social Share Icons -->
  < mj-section background-color="#00a8df">
    < mj-column>
      < mj-text align="center" color="#fff">Please share if you enjoyed!< /mj-text>
      < mj-social mode="vertical" display="twitter facebook" />
  < /mj-column>
    < /mj-column>
  < /mj-section>
< /mj-body>