Having to send some sort of transactional email in order to notify a user of an event or a task that needs to be taken care of is a commonplace requirement for many applications.

While there’s no shortage of libraries, APIs and services that help with one or more aspects of this requirement there’s no simple yet comprehensive solution that covers everything from triggering an email event, managing the content of different notification email templates and actually sending the email.

In order to address this issue I created a Spring Boot-based service called MailTrigger (licensed under Apache License, Version 2.0). MailTrigger allows you to asynchronously send emails using an HTTP API. Emails are represented as channels and generated from Markdown templates which are kept in the same source code repository as the software itself. This allows you to simply clone or fork the MailTrigger GitHub repository and use that for managing your email templates.

Once the service is started you can trigger an email by sending an HTTP request like this one:

curl -d '{"TO": "test@test.com", "FIRST_NAME": "Jack"}' -H 'Content-Type: application/json' -X POST http://localhost:8080/api/v1/sendMail/test_channel

This will asynchronously send an email to test@test.com. MailTrigger isn’t a full-blown email infrastructure provider like MailGun or SendGrid but rather allows you to use your own existing SMTP server. Since it can take up to a few seconds for an SMTP server to respond on successful email dispatch it’s important to call actions that send email asynchronously so the user doesn’t have to wait for the server to respond but can continue working with the application.

MailTrigger manages email templates by a channel parameter. In the case of the request above the channel parameter value is test_channel. MailTrigger takes that value and loads a Markdown template from this path:

src/main/resources/com/bjoernkw/mailtrigger

This Markdown template contains the email text alongside with replacement variables like ${FIRST_NAME}. These replacements can be supplied as a JSON object of key-value pairs in the request body of the HTTP request (see the curl example above).

If you want to add a new kind of email all you have to do is create a new template in the path mentioned above and redeploy the service (preferably using an automated build pipeline). This allows you to add new notifications with minimal development effort because all you have to do in terms of actual programming is adding the HTTP call at the appropriate place in your application’s source code.

Many source code management tools like GitHub or GitLab these days include in-browser Markdown editors. Therefore your email content doesn’t necessarily have to be managed by developers anymore. Since MailTrigger is designed as a microservice it can be deployed automatically and separately from your main application using standard build pipelines. This minimises developer involvement and allows developers to focus on more important and more demanding tasks.