Java library to convert MJML templates to HTML
Clone or download
atrujillofalcon Merge pull request #53 from atrujillofalcon/dependabot/gradle/develop…

Bump kotlin_version from 1.3.10 to 1.3.11
Latest commit c897bb7 Dec 8, 2018
Type Name Latest commit message Commit time
Failed to load latest commit information.
.gitignore Ignoring out folder Jun 10, 2018 Adding LICENSE and initial README Nov 3, 2017 [Gradle Release Plugin] - pre tag commit: '1.5.1'. Sep 21, 2018
build.gradle Bump kotlin_version from 1.3.10 to 1.3.11 Dec 7, 2018 [Gradle Release Plugin] - new version commit: '1.5.2-SNAPSHOT'. Sep 21, 2018
gradlew.bat Initial commit Nov 3, 2017

Mjml Rest Client

CircleCI Codacy Badge codecov

Mjml is the best responsive mail framework, I love it ❤️. I created this project to have a Java library that use the mjml API to convert a mjml template into valid html ready to use.

Built With


To include this library into your project your only need to add the dependency.




compile "es.atrujillo.mjml:mjml-rest-client:1.5.1"


Creating templates

This library includes Thymleaf engine to allow to create dynamic templates before to send to Mjml API.

We have two options for templating mjml mails. In-memory String or File.

File templates

Now we're going to see how create the template from a file source to create a fun mail. Let's imagine that we have a Thymeleaf template in a file called readme-template.mjml with the following content:

                    <mj-text font-style="bold" align="center" color="#8B9C36"><h1 th:text="${myTitle}"></h1></mj-text>
                    <mj-text font-style="bold" align="center" color="#8B9C36"><h3 th:text="${myDescription}"></h3></mj-text>
                        <mj-carousel-image src=""/>
                        <mj-carousel-image src=""/>
                        <mj-carousel-image src=""/>

If we look, we have two variables: myTitle and myDescription that we're going to replace dynamically. Let's see how use the File Template mode:

File fileTemplate = new File("/path/to/mjml/readme-template.mjml");
Context contextVars = new Context();
contextVars.setVariable("myTitle","Dog Gallery");
contextVars.setVariable("message","This is my dog Bilbo, modeling for the camera");
String mjmlTemplate = TemplateFactory.builder()

Final Result of Template

Mjml Screenshoot

In-Memory String templates

private static final String DUMMY_TEMPLATE = "<mjml><mj-body><mj-container><mj-section><mj-column><mj-text th:text=\"${message}\"></mj-text></mj-column></mj-section></mj-container></mj-body></mjml>";
Context contextVars = new Context();
contextVars.setVariable("message","Hello MJML");

String mjmlTemplate = TemplateFactory.builder()

API Credentials

We already have the template, but before to call to API we need the API credentials to initialize our service client.

You can obtain the credentials here.

Before calling our service we have to create an instance of MjmlAuth through the MjmlAuthFactory class. We have three options:

//Get credentials from environments variables
MjmlAuth systemEnvAuthConf = MjmlAuthFactory.builder()
                .mjmlKeyNames(MJML_APP_ID, MJML_SECRET_KEY)

//Enter in-memory string credentials directly into auth factory
MjmlAuth memoryAuthConf = MjmlAuthFactory.builder()
                .mjmlCredentials(mjmlAppId, mjmlSecretKey)

//Get credentials from properties file
MjmlAuth propertyAuthConf = MjmlAuthFactory.builder()
                .mjmlKeyNames(appPropKey, secretPropKey)

Obtaining final HTML

Finally, we just need to instantiate our client with the credentials obtained and use it to convert the template into the final HTML to send it to whoever we want.

MjmlService mjmlService = new MjmlRestService(authConfInstance);

String resultHtmlMail = mjmlService.transpileMjmlToHtml(mjmlTemplate);
//after obtain the html you can send it using your email service implementation.

Running the tests

First you have to set MJML_APP_ID and MJML_SECRET_KEY environment variables.

Execute from root folder:

gradle test


Arnaldo Trujillo

See also the list of contributors who participated in this project.


This project is licensed under the Apache License - see the file for details