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.
- 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
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"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.
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
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(); 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();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.First you have to set MJML_APP_ID and MJML_SECRET_KEY environment variables.
Execute from root folder:
gradle testSee also the list of contributors who participated in this project.
This project is licensed under the Apache License - see the LICENSE.md file for details