Creating beautiful looking, responsive mails with MJML and Spring Boot
Motivation
Thinking of projects I’ve worked on in the past, e.g. mobile apps or websites it always was quite a challenge to make sure it is compatible and responsible with all kind of possible devices which differ in screen sizes, hardware and software capabilities.
But there is one use case which is probably the worst of all of them:
Creating a beautiful mail that is responsive, includes images and is compatible with all sort of mail viewer applications
Why is this so you may ask? Well when it comes to creating mail templates a developer needs to support a wide range of email clients which all have their own implementation of specific CSS rules. That means if an email looks as expected in e.g. the newest Outlook version this does not guarantee it looks the same in Apple Mail. Often you face issues with the alignment of text or images are not displayed correctly.
With these problems in mind, how can you create responsive mails that support all sort of clients? The hard way would be to learn all the specific rules of each major client you want to support and implemented multiple conditional CSS to make sure the outcome is correct. This is really time intensive, hard to get perfect and increases the amount of code needed for a simple mail by a lot.
But luckily there is a better approach:
MJML — The Responsive Email Framework which solves all the issues mentioned above and makes creating nice looking emails so much simpler.
MJML provides a framework which is easy to learn and use and helps you to build the email template you’ve dreamed of without bothering with the custom CSS and support of different clients. The HTML will be automatically generated for you by the MJML engine. For that you will create your template using MJML objects and send the structure to an MJML Server which renders the code into HTML. The generated snippet than can be displayed in any mail client that is supported by the framework. The company behind MJML offers a REST-Service that can be used for this purpose and only requires a simple registration (https://mjml.io/api).
Unfortunately for most of the companies that think about using MJML as a solution for creating responsive mails this is not a solution due to privacy reasons when sending dynamically filled MJML templates with possible client data to an unknown REST API. To solve this issue you can run your own engine on your own server.
Hosting your own MJML Server
There are multiple solutions, one of my favorites is the following package:
MJML wrapped in Express for use over HTTP (github.com) by danihodovic
This package is a simple Express-JS server which embeds the MJML engine and exposes REST-endpoints that you can call from your application. It also comes with a preconfigured Dockerfile that makes it easy to run without figuring out the required dependencies.
Dynamically generate MJML mails with Spring Boot
Spring Boot is one of the most common frameworks being used right now to implement enterprise ready backends for different applications. Due to this the scope of an example implementation is limited to Spring Boot in this post. But the technique, architecture and flow should also work for different frameworks.
The proposed architecture consists of two major components. First the standalone MJML-Server that is responsible of rendering a MJML-Template into mail-ready HTML. It is using a simple Express-JS server to expose the required REST-endpoints. The server does not implement any authentication. This obviously only works if you control the network and can restrict the access. It should be protected by an authentication mechanism like Basic Auth if its accessible to the internet.
The second major component is the Spring Boot application. Here we have 3 smaller components that are used combined to fulfill the task, a rest controller, Thymeleaf as a template builder and the prepared MJML-template to define the static mail structure.
The implementation is following this flow:
- Create a MJML Template and place it within your application
Creating a nice looking template can be easily done by using an dynamic builder tool like https://github.com/artf/grapesjs-mjml. - When it comes to mails, often it is a need to dynamically populate those with individual data. To implement this a dynamic template engine (e.g. Thymeleaf) can be used. It allows you to define variables within the script code that are dynamically replaced by the engine during rendering.
- As a last step you need to call the MJML-Server Endpoint “/render” with a post request. An example can be found below.
Example request to the MJML-Server:
Curl Request:
curl -d ‘{“mjml”:”<mjml></mjml>”}’ -H “Content-Type: application/json” -X POST https://mjml-server.example.de/v1/render — insecureResponse Object:
{
“html”: “,
“mjml”:” <html ……</html>”,
“mjml_version”:”⁴.6.2",
“errors”:[]
}
In the following chapter you can find an example implementation of a MailAdapter and a MailService written in Kotlin. This allows you to render a mail with an image and dynamically replaced variables. The rendered mail will look similar to the one below.
But before we jump to the code I hope this post helped you to get a better understanding regarding the challenges when it comes to mails in general but especially showed how you can utilize existing tools to make your life easier.
If you have questions regarding the architecture or implementation feel free to leave a comment. And if this post helped your feel free to leave a clap :)