README.md

Mjml Rest Client

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

• Kotlin - The future of JVM languages
• Gradle - Dependency Management
• Spring Rest Template - Used to communicate with API
• Jackson - Best databind Java library
• Thymeleaf - Template Engine

Installing

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

Maven:

<dependency>
    <groupId>es.atrujillo.mjml</groupId>
    <artifactId>mjml-rest-client</artifactId>
    <version>2.0.1</version>
</dependency>

Gradle:

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

Usage

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:

<mjml>
    <mj-body>
        <mj-container>
            <mj-section>
                <mj-column>
                    <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>
                        <mj-carousel-image src="https://unblogdecode.es/gallery/dog1.jpg"/>
                        <mj-carousel-image src="https://unblogdecode.es/gallery/dog2.jpg"/>
                        <mj-carousel-image src="https://unblogdecode.es/gallery/dog3.jpg"/>
                    </mj-carousel>
                </mj-column>
            </mj-section>
        </mj-container>
    </mj-body>
</mjml>

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()
               .withFileTemplate()
               .template(fileTemplate)
               .templateContext(contextVars)
               .buildTemplate();                

Final Result of Template

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()
                .withStringTemplate()
                .template(DUMMY_TEMPLATE)
                .templateContext(contextVars)
                .buildTemplate();              

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()
                .withEnvironmentCredentials()
                .mjmlKeyNames(MJML_APP_ID, MJML_SECRET_KEY)
                .build();

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

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

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

Author

Arnaldo Trujillo

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

License

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