Mjml Rest Client
Mjml is the best responsive mail framework, I love it
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
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