How to Create a Custom Mautic Theme with Your Corporate Identity. Step-by-Step Guide by Logicify

Daryna Tkachenko

If you ever struggled creating custom themes in Mautic using your favorite layout design tools, we are more than sure you’ll like this article. Here's how to add a new theme for your Mautic emails in just five simple steps.

6 min read

In a recent article, we introduced Mautic as an open source marketing platform for contacts outreach via email campaigns. Default Mautic email templating is not too sophisticated and flexible, so we recently released an open-source bundle that extends native emails with TWIG blocks and allows to code a condition inside an email template to make it reusable. Check this out!

Related articles

This time, we’d like to introduce yet one more open source tool for Mautic that we developed - a bootstrap project for Mautic theme with configured SCSS compiler, CSS inliner and HTML minifier.

Challenges of Mautic Themes

Since version 2.1.0, Mautic has a Theme Manager and a handful of standard themes for emails and landing pages. However, these are quite generic and hardly fit business needs of a company with existing corporate identity, which requires that all pieces of content are consistent and follow company-specific brand book in terms of design and layout.

Recently, we integrated Mautic with our client’s e-commerce application; afterwards, our layout designer was to make up branded email templates following the company’s style guide. This was a challenge because

  • there is no (at least to our knowledge) way to easily integrate layout designer toolchain with Mautic. Most layout designers lack technical skills and expertise to do this integration on their own.
  • one Mautic theme = one email template only. Our client needed three. So, we were to create (read: copy-paste) a separate theme for every email template with just slightly different layouts. This was quite tiresome and time-consuming.

We did not find proper canned pipeline to create and package Mautic themes, so we developed it on our own. Its code is open source, so you are welcome to use it too.

Our Solution - A Skeleton for Mautic Themes

Our Mautic theme skeleton incorporates a set of popular tools used by layout designers into a single pipeline. What is more, it allows to manage as many templates as you need from a single repository, i.e. using the same code base. You may use this GitHub repository to start configuring your own custom theme on top of default Mautic editor (currently, for emails only). The repository is licensed under MIT license, for free even for commercial purposes.

Skeleton Features

  • With the skeleton, you may compile themes in zip format to upload them via Mautic web interface.
  • The skeleton allows to work with email content\snippet that is not a part of your theme, leveraging all power of HEML and SCSS.
  • With the skeleton, you can support generation of multiple themes using the same source code base.
  • The skeleton’s deployment for development purposes is easy. Your compiled themes could be automatically copied to corresponding Mautic folder, and you can work with them immediately.
  • There is no need to run compilation after each change. The skeleton re-compiles automatically and deploys the changes every time you save the source code.

Tools Incorporated into the Skeleton

Email layouting in Mautic would be way less painful thanks to the following tools incorporated into the skeleton:

SASS Logo SCSS Compiler, which prompts you to use powerful SCSS syntax and mixins, which would be CSS compatible.

HTML 5 Logo HTML Minifier, which compresses your HTML files to optimize the size of your final email.

HEML Logo HEML, an open source framework for building responsive, clean, and well-designed emails using the same-name markup language.

It gives you the native power of HTML without having to deal with all of the email quirks. It also does a great job on inlining CSS\SCSS into HTML, so you can keep styles in separate files and forget about copy-and-paste approach.

HEML ensures better rendering compatibility and resilience of your email layout in all email clients. With it, everything would look pixel perfect on both desktop and mobile devices - just the way you designed it. If you never tried HEML before, here is a convincing example in favor of this language. Check out layouts in HTML and HEML for the following email:
Sample Email

You could see how light HEML looks on the page and how time-saving it is for layout designers.

5 Simple Steps to Create a Custom Theme in Mautic

We assume you already have an instance of Mautic configured and deployed either locally (preferred) or on a remote machine. You would also need Node.js installed on our workstation. To familiarize yourself with Mautic themes building basics, check out the official guide.

To create a custom theme for Mautic and incorporate your corporate layout standards in it, follow these simple steps.

Step 1. Download or fork/clone this GitHub repository. Please make sure to keep the project's folder outside your Mautic folder. Open terminal, navigate to the project directory, and run npm install to download all dependencies.

Please note that the repository does not contain any ready-to-use theme. It could be used as a bootstrap project (skeleton) for building your custom themes.

Step 2 (optional). Open package.json and set property mautic.mauticBasePath to point location of Mautic root folder (this may be either a relative or an absolute path). You may skip this step, however, in this case, automatic deployment and rebuild features will not work.

Step 3. Entitle your custom theme.

  1. Edit section mautic.themes of the package.json file:
    а) Set name, avoiding spaces and special characters. It will be used to name files and folders.
    b) Update verboseName. This is the title of your Mautic theme to be displayed in the list of available themes.
  2. Edit src/config.json file:
    a) Leave name empty.
    b) Update author and authorUrl fields.

Step 4. Feel free to update files under src/assets and src/heml folders with your styles and slicing for email templates.

Step 5. Build your theme with npm run package. Output should appear under build/themes directory. Ta da!

You might also be interested in other usage scenarios for our theme skeleton.

Building Code Snippets for Mautic Emails

The toolchain incorporated into the skeleton could also be used for email templates that are not a part of your custom theme. Use compile command for this:

  1. Create a file for your code snippet under src/emails folder. Note: make sure to use .heml as an extension, e.g. welcome-email.heml
  2. Make up an email template using HEML and CSS.
  3. Run npm run compile -- --email FILE_NAME_WITHOUT_EXTENSION, e.g. npm run compile -- --email welcome-email Note: the extension is missing here.
  4. Find your compiled snippet under build/emails. You can just copy the code and paste it into native Mautic editor.

Maintaining Multiple Themes

Mautic allows to maintain a single email template per a theme. So, if you need multiple email templates with slightly different layouts, you would be forced to create a dedicated theme for each. This means you would need to copy and paste the themes and manage them all manually, which is not productive. Our skeleton allows to easily build and manage multiple themes using a single code base.

Here’s how you could do this for two themes my-theme-1 and my-theme-2:

  1. Edit section mautic.themes of the package.json file:
  "themes": [
      "name": "my-theme-1",
      "verboseName": "My Theme 1",
      "emailTemplateFile": ""
      "name": "my-theme-2",
      "verboseName": "My Theme 2",
      "emailTemplateFile": ""

Please note that the file’s name should follow this format "email.your-theme.heml.twig" (you are allowed to change part in bold only).

  1. Copy src/heml/email.deafult.heml.twig two times to create and .heml.twig

  2. Make up two different email layout templates.

  3. Run npm run package to compile both. You should get 2 zip files under built\themes.

Find more about the skeleton on GitHub or ask us if you have any questions We are eager to get feedback if you tried using our skeleton for your custom themes.

Related articles


Scroll top