Creating a Mautic Email Theme Using Foundation for Emails

Mautic Logo

On first glance, the blank Mautic theme looks like the perfect starting point for a simple HTML email, you just drag and drop the elements that you need into the layouts, add your images and text, select some colours and it's done.

Unfortunately, after testing the resulting emails in different email clients and web apps the results weren't totally as expected and Outlook (Of course) was all over the place.

Having seen issues with other default themes in certain places I didn't want to start with a copy of another theme that I might need to end up fixing so I went on the look for a better way to do things.

Enter Foundation for Emails.

Foundation for Emails has been around for quite a while now and is currently on version 2. I'd heard about it in the past but had never really needed it so I didn't get past the example themes.

Having just built a theme using it, I feel that there are some very large benefits to using it for Mautic Email themes. There are also a few manual things that need to be done to actually work the output into a theme but they are pretty simple and I can see myself using this a lot in the future.

Some of the benefits:

Inky Markup - If you have ever written email markup (Or built a website in the 90's) by hand then you know it sucks. Some editors can help with a visual representation but it's still a mess. Inky converts simple tags like <wrapper>, <row> and <column> into the table mess you know and hate. No room for error, everything is built from clean markup.

Sass - Styling uses Sass so it's easy to keep things consistent and concise, the same as in your web projects. When it comes to build time, all the styles are inlined as they should be for Emails and the Mautic editor seems to respect these styles and uses them when extending demo content.

Gulp - Once setup, your new project is watched for changes. Sass automatically compiles when you save a file, images added to the assets directory are automatically compressed.

BrowserSync - Working together with Gulp, your browser is automatically refreshed to see any changes you have made. Not just the browser you are working on, you can connect multiple devices and have them all update at the same time, so you can check changes across a range of devices whilst you are in development.

It can also use handlebars templating (Which we won't go into here).

All of these features together make email templating a breeze rather than a chore and you can knock out some decent templates in a short space of time.

So let's get started and build one.

Installing Foundation for Emails

You need to have Node installed to create a new project. We're going to be using the sass version so check out the official docs here for full install instructions.

Firstly, install the Foundation stack globally so we can use the 'foundation' command:

npm install --global foundation-cli

Then navigate to a directory you want to develop in and create a new email project.

foundation new --framework emails

You will be asked for a project name which will be the name of the folder all needed files will be installed into and then the install will take a few minutes to download all the needed dependencies.

Once everything has installed, cd into the new project folder and start the watcher with the command:

foundation watch

or

npm start

This will open your browser and show the contents of the src/pages/index.html file. You can click the links to see some of the demo files that come with the project.

Creating Our Layout

Let's start by creating a blank file in the pages file called mautic.html

Each file in the pages folder starts with some yaml style header information where we need to specify the subject for the email. Since the subject in a Mautic theme is going to be dynamic we can just set the subject to subject and then modify it when we set up our Mautic theme later on.

Start the file with:

---
subject: subject
---

NOTE: Don't add {subject} as the subject as the brackets will break the parser and result in an error. We'll fix this later.

Now change the url of the browser tab that opened to look at our new file: http://localhost:3000/mautic.html

You should see an empty browser tab with the page title set to subject.

What you are actually seeing here are the files that have been compiled to the /dist folder. If you now open up /dist/mautic.html you will see the full code that's being shown in the browser, namely all the scaffolding that the framework adds:

Again, take a look at the docs for the sass version to fully understand what we are doing here and to see what elements are available by default.

If you check through the sample templates you will see that each one generally only has one <wrapper> tag wrapping the whole output of the template. Due to the way mautic works, we're going to use a wrapper tag for each different section so that it's possible to change the colour of the background in the Mautic editor.

So let's add a header and a dummy image for our logo. Add the following to the mautic.html file after the header information containing the subject:

<wrapper data-section-wrapper="1" class="header">
  <container>
    <row class="collapse">
      <columns small="12">
        <div data-slot-container="1">
          <div data-slot="image">
            <img src="http://placehold.it/580x150" alt="">
          </div>
        </div>
      </columns>
    </row>
  </container>
</wrapper>

The wrapper is a full-width element so that we can change the background colour. The data attributes that you can see are used by the Mautic editor so that it knows how different content can be edited and how they should be displayed.

The collapse class removes the padding around the row so that our logo image will be the full width of the container. At the moment you will see the header background as grey but we will change that later in the sass files.

The data-slot-container attribute lets Maulic know that the user should be allowed to add new elements into this slot.

The data-slot image that we add by default has a type of image and a default image. Mautic will know that this is editable and let the user change the image as if it was an image element that they had dragged into the layout themselves.

I'm using a placeholder image but we will look at how these can be changed to a specific image later on.

Let's add another section with a hero image to start off the email:

<wrapper data-section-wrapper="1">
  <container data-section="1">

    <row class="collapse">
      <columns small="12">
        <div data-slot-container="1">
          <div data-slot="image">
            <img src="http://placehold.it/580x300" alt="">
          </div>
        </div>
      </columns>
    </row>

  </container>
</wrapper>

Very similar again except we also have a data-section attribute on the container tag which lets the user drag it around in the editor.

Now let's add some actual (fake) text under the image:

<wrapper data-section-wrapper="1" class="secondary">
  <container data-section="1">

    <row>
      <columns large="12">
      <div data-slot-container="1">
        <div data-slot="text">
          <h2 style="text-align: center;">Hi {contactfield=firstname}!</h2>
          <p>Lorem ipsum dolor sit amet, consectetur adipisicing elit. Nisi repellat, harum. Quas nobis id aut,
            aspernatur, sequi tempora laborum corporis cum debitis, ullam, dolorem dolore quisquam aperiam!
            Accusantium, ullam, nesciunt. Lorem ipsum dolor sit amet, consectetur adipisicing elit. Ducimus
            consequuntur commodi, aut sed, quas quam optio accusantium recusandae nesciunt, architecto
            veritatis. Voluptatibus sunt esse dolor ipsum voluptates, assumenda quisquam.</p>
          </div>
        </div>
      </columns>
    </row>
    
  </container>
</wrapper>

The only thing that is different here to the previous two sections is that we have specified a slot type of 'text' which will let the user edit with the standard editor.

Then we just need a footer with some text content and the usual view in browser and unsubscribe links:

  <wrapper data-section-wrapper="1" class="footer">
    <container data-section="1">
      <spacer size="20"></spacer>
      
      <row>
        <columns large="12">
        <div data-slot="text">
          <p>Copyright © 2017 My Company Ltd, All rights reserved.</p>
          <p>Company Address</p>
        </div>
        <center>
          <menu>
            <item href="{webview_url}">View in Browser</item>
            <item href="{unsubscribe_url}">Unsubscribe</item>
          </menu>
        </center>
      </columns>
      
    </row>
  </container>
</wrapper>

By now you should be seeing something like this in your browser:

Basic Foundation for Emails layout

That's looking pretty good, but we're not going to send anything looking like this, so let's change some of the sass files to modify the design.

Sass can be found in the src/assets/scss folder. app.scss is the default file which first includes _settings.scss where all the default variables are kept, then it includes template/_template.scss which is where we can add custom styles to our email.

If you open up _template.scss you will see that it already includes some demo styles for the example templates that comes with the starter project. You can either keep these or just delete them (keep all the rules related to tables).

Let's change the header wrapper background so that it's white and also change the body background to white so everything matches. Search for the following and use $white as the value:

.body {
  background: $white !important;
}

// Full Width Headers
.header {
  background: $white;
}

.wrapper.secondary {
  background: $white;
}

You should now have a white background for the whole template.

Let's give the header and footer container area a branded colour background and adjust the text colour for those areas.

You may have noticed that the header has a class of 'header' and the footer a class of 'footer'. We can target these classes with our sass and Foundation is smart enough to know what these styles should be applied to in the resulting table format.

Let's start with black as an example. Add the following to the _template.sass file

.header .container {
  background: $black;
}

.footer .container {
  background: $black;
}

.footer, .header {
  p,
  a {
    color: #fff;
    padding-top: 15px;
    text-align: center;
    font-size: $small-font-size;
  }
}

The footer should now be black with white text and if any other blocks are added to the header area they will get the same styling.

We still have blue links for the bottom links though and that doesn't look good.

Update the settings file to change the default colour of menu links:

$menu-item-color: $white;

By now you should have something looking like this:

Foundation for emails template after styling modifiactions

If you want to add your logo at this point you can add your image to the src/assets/img and reference it relatively and the image will be automatically compressed which can be used later when we convert the output to a Mautic template.

Inlining

Now we have a pretty blank theme that we can use, we need to inline all the styles that come from our sass files.

Go back to the command prompt and stop Foundation from watching by pressing 'ctrl +c'. Now create the usable distribution files by running the following command:

npm run build

The files created in the dist folder will now be regenerated to use inline styles in a way that we can use to create the Mautic template. The only issue we have is that they are minified and the resulting files in the dist folder will look like this:

Compressed Foundation Email

We have all the inline styles we need, but the format isn't great for working it into a Mautic theme.

To fix this, you can modify the gulpfile.babel.js file in the root of the project to turn off the collapseWhitespace flag:

.pipe($.htmlmin, {
      collapseWhitespace: false,
      minifyCSS: true
    });

You can also use an online service like this one or an editor plugin for beautifying compressed code.

You should now have something more readable.

Creating the Mautic Theme

We now have the HTML we need to start the theme, so we need to start putting together a package for Mautic.

Create a folder with the same name as you want the theme to be called and create the files shown below:

Mautic theme folder structure

NOTE: For unsubscribe links to work, the theme also needs to include a base.twig.html and message.twig.html file in the html folder. Users will still get unsubscribed but without the files, they will see a 500 error in the browser. Copy these 2 files from another theme (Such as nature) and customise them as you wish.

The config.json file needs to name the theme and explain what templates it contains. Rename the following as you wish:

{
   "name": "My Theme",
   "author": "Robert Went",
   "authorUrl": "https://robertwent.com",
   "features": [
     "email"
   ]
 }

Copy any images that you compressed or just want to use into the img folder.

Now copy the beautified html output from Foundation into the /html/email.html.twig file.

The first thing we need to do is change the title tag from being the fixed text 'subject' by replacing it with a tag that Mautic can use to replace with the actual subject set in the admin area:

<title>{subject}</title>

Now you can replace any image tags with images in the img directory that you want to show as default, like replacing the logo image.

Replace the image src attribute with the following tag and change the filename to the file you placed in the img directory:

{{ getAssetUrl('themes/'~template~'/img/my_logo_file.jpg', null, null, true) }}

The thumbnail_email.png file in the root of the folder is the image that shows where you select a template in the Email edit screen. You can use any image you want but it should be png format and 575x600px (WidthxHeight).

And that's it. Image links should now work, unsubscribe and browser view links should be preserved from our original Inky file and we should be ready to upload.

Uploading the New Theme

FTP the folder to the /themes directory of your install. It should now show in the template selection area of the email edit screen:

New theme is available in the editor

You can then select the new theme and change all the default content we added in Foundation as well as add new blocks to the main content area.