Rich HTML email in Spring with Thymeleaf

By José Miguel Samper <jmiguelsamper AT>

In this article we will show how to use Thymeleaf templates for composing email messages of several kinds, and we will integrate this with Spring's email utilities in order to configure a simple but powerful email system.

Note that, although this article —and the corresponding example app— uses the Spring Framework, Thymeleaf can also be used for processing email templates in an application without Spring.


This article assumes you are familiar with both Thymeleaf and Spring 3. We will not dive into Spring Mail details, for further information please take a look at the Email chapter at the Spring Documentation.

Example application

All the code in this article comes from a working example application you can download from the documentation page. Downloading this application, executing it and exploring its source code is highly recommended (note that you will have to configure your SMTP user name and password at

Sending email with Spring

First, you need to configure a Mail Sender object in your Spring configuration, as in the following XML (your specific configuration needs might differ):

Spring provides a class called MimeMessageHelper to ease the creation of email messages. Let's see how to use it together with our mailSender.

Thymeleaf HTML email templates

Using Thymeleaf for processing our email templates would allow us to use some interesting features:

Also, given the fact that Thymeleaf has no dependencies on the servlet API, there would be no need at all to create or send this HTML email from a web application. The techniques explained here could be used with little or no change in a standalone application with no web UI.

Our goals

Our example application will be sending three types of emails:

  1. Simple HTML (with internationalized greeting).
  2. HTML text with an attachment.
  3. HTML text witn an inline image.

Spring configuration

In order to process our templates, we will need to configure our TemplateEngine at spring-servlet.xml:

Note that we have configured two template resolvers for our engine: one for the email templates —which come from our resources directory and therefore are loaded by a ClassLoaderTemplateResolver— and another one for the web templates that support the example application itself —which loads its templates from the servlet context, as most Spring web applications do.

Of course, if we were creating a non-web application, we would not need either the webTemplateResolver or the viewResolver beans at all.

Executing the Template Engine

At some point in our code, we will need to execute our template engine in order to create the text of our messages. We have chosen to do this in an EmailService class, so that it stays clear that we consider this a responsibility of our business layer (and not the web layer).

As usual in Thymeleaf, before executing we will need to populate a context containing all the variables we want to use during template execution. Given the fact that our email processing is not web-dependent, an instance of Context will do:

Our email-inlineimage.html is the template file we will use for sending emails with an inlined image, and it looks like:

Let's remark some points:

Putting it all together

The service class

Finally, let's see how the method executing this email template at our EmailService service class would look like:

Note that we have used an object to attach the image uploaded by the user, which we previously converted into a byte[].

You could also make use of FileSystemResource to attach a file directly from the filesystem —thus avoiding loading it into memory—, or UrlResource to attach a remote file.

The controller

Now for the controller method that calls our service:

Cannot be easier. Note how we use a Spring MVC MultipartFile object to model the uploaded file and pass its contents on to the service.

More examples

For the sake of brevity, we have only detailed one of the three types of email we want our application to send. However, you can see the source code required for creating all three types of emails at the springmail example application you can download from the documentation page.