A set of services and tools for sending emails in a Spring Boot application using plain text, html or a template engine to generate dynamic content.
Source Website: github.com/ozimov/spring-boot-email-tools
Latest Release: 0.5.1
Latest Artifacts: it.ozimov:spring-boot-email-core, it.ozimov:spring-boot-freemarker-email,
it.ozimov:spring-boot-mustache-email, it.ozimov:spring-boot-pebble-email, it.ozimov:spring-boot-thymeleaf-email
Continuous Integration:
[
The project relies on a templateless module it.ozimov:spring-boot-email-core that provides the core
features (e.g. sending emails, scheduling and prioritizing, persistence). Since it is templateless, it does not provide
any implementation of the service to be used to generate the body of the email via template engine.
If you want to use one of the template engines supported by this project (i.e. Freemarker,
Mustache, Pebble and Thymeleaf), you can use the dedicated templatefull
module that is shipped with the core module. The standard naming for the templatefull module is
it.ozimov:spring-boot-{template_engine_name}-email (where {template_engine_name} is for instance pebble).
Latest release is 0.5.1. To use the core module, you can import the following dependency in Maven
<dependency>
<groupId>it.ozimov</groupId>
<artifactId>spring-boot-email-core</artifactId>
<version>0.5.1</version>
</dependency>To embed the module that includes the Freemarker template engine, you can use the following Maven dependency:
<dependency>
<groupId>it.ozimov</groupId>
<artifactId>spring-boot-freemarker-email</artifactId>
<version>0.5.1</version>
</dependency>for Mustache:
<dependency>
<groupId>it.ozimov</groupId>
<artifactId>spring-boot-mustache-email</artifactId>
<version>0.5.1</version>
</dependency>for Pebble:
<dependency>
<groupId>it.ozimov</groupId>
<artifactId>spring-boot-pebble-email</artifactId>
<version>0.5.1</version>
</dependency>and for Thymeleaf:
<dependency>
<groupId>it.ozimov</groupId>
<artifactId>spring-boot-thymeleaf-email</artifactId>
<version>0.5.1</version>
</dependency>Remember that if you import the template-full module, the core module should not be required.
In your main Spring Boot application, you need to add the annotation @EnableEmailTools to
enable support for all the services and controllers defined in the Spring Boot Email module, e.g.:
@SpringBootApplication
@EnableEmailTools
public class MainApplication {
public static void main(final String ... args) {
SpringApplication.run(MainApplication.class, args);
}
}in you application.properties set the configuration needed to send the emails, e.g. if you want to send
the emails using a Gmail account you can set:
spring.mail.host=smtp.gmail.com
spring.mail.port=587
spring.mail.username[email protected]
spring.mail.password=V3ry_Str0ng_Password
spring.mail.properties.mail.smtp.auth=true
spring.mail.properties.mail.smtp.starttls.enable=true
spring.mail.properties.mail.smtp.starttls.required=truePlus, the additional properties must be added to prevent using the persistence layer
spring.mail.scheduler.persistence.enabled=false
spring.mail.scheduler.persistence.redis.embedded=false
spring.mail.scheduler.persistence.redis.enabled=falseTo send an email, use the EmailService in your Spring Boot application. E.g.
@Autowired
public EmailService emailService;
public void sendEmailWithoutTemplating(){
final Email email = DefaultEmail.builder()
.from(new InternetAddress("[email protected]", "Marco Tullio Cicerone "))
.to(Lists.newArrayList(new InternetAddress("[email protected]", "Pomponius Attĭcus")))
.subject("Laelius de amicitia")
.body("Firmamentum autem stabilitatis constantiaeque eius, quam in amicitia quaerimus, fides est.")
.encoding(Charset.forName("UTF-8")).build();
emailService.send(email);
}The previous code will send a plain text message. To obtain some more dynamic fancy emails, you have two options:
i) the former and easier-to-use is to use a templatefull module (e.g. based on Freemarker);
ii) the latter (which requires some effort on your side) needs an an implementation of the
interface it.ozimov.springboot.templating.mail.service.TemplateService.
The aforementioned interface requires a component that implements the following method
String mergeTemplateIntoString(String templateReference, Map<String, Object> model)
throws IOException, TemplateException;Assuming you opted for one of the previous options, just put the template in the required folder
(e.g. templates under resourses) and try to execute the following code (it works with Freemarker):
@Autowired
public EmailService emailService;
public void sendEmailWithTemplating(){
Arrays.asList(new Cospirator("[email protected]", "Gaius Cassius Longinus"),
new Cospirator("[email protected]", "Marcus Iunius Brutus Caepio"))
.stream.forEach(tyrannicida -> {
final Email email = DefaultEmail.builder()
.from(new InternetAddress("[email protected]", "Gaius Iulius Caesar"))
.to(Lists.newArrayList(new InternetAddress(tyrannicida.getEmail(), tyrannicida.getName())))
.subject("Idus Martii")
.body("")//Empty body
.encoding(Charset.forName("UTF-8")).build();
//Defining the model object for the given Freemarker template
final Map<String, Object> modelObject = new HashMap<>();
modelObject.put("tyrannicida", tyrannicida.getName());
emailService.send(email, "idus_martii.ftl", modelObject);
};
}
private static class Cospirator {
private String email;
private String name;
public Cospirator(final String email, final String name){
this.email = email;
this.name = name;
}
//getters
}where the template idus_martii.ftl is a Freemarker file like:
<!doctype html>
<html>
<body>
<p>
Tu quoque, <em>${tyrannicida}</em>!
</p>
</body>
</html>The following example shows how to send and email that includes an inline image.
@Autowired
public EmailService emailService;
public void sendEmailWithTemplatingAndInlineImage(){
final Email email = DefaultEmail.builder()
.from(new InternetAddress("[email protected]", "Gaius Iulius Caesar"))
.to(Lists.newArrayList(new InternetAddress("[email protected]", "Marcus Iunius Brutus Caepio")))
.subject("Idus Martii")
.body("")//Empty body
.encoding(Charset.forName("UTF-8")).build();
//Defining the model object for the given Freemarker template
final Map<String, Object> modelObject = new HashMap<>();
final File imageFile = //load your picture here, e.g. "my_image.jpg"
modelObject.put("tyrannicida", tyrannicida.getName());
final InlinePicture inlinePicture = DefaultInlinePicture.builder()
.file(imageFile)
.imageType(ImageType.JPG)
.templateName("my_image.jpg").build());
emailService.send(email, "idus_martii.ftl", modelObject, inlinePicture);
}where the template idus_martii.ftl is a Freemarker file like:
<!doctype html>
<html>
<body>
<p>
<img src="my_image.jpg" />
</p>
</body>
</html>be sure that the name provided in the InlinePicture matches with the one used in the template file path included, if
any was set. This means that if in the template you have <img src="images/my_image.jpg" /> then the definition has to be
changed as follows:
final InlinePicture inlinePicture = DefaultInlinePicture.builder()
.file(imageFile)
.imageType(ImageType.JPG)
.templateName("images/my_image.jpg").build());This is required to set the a proper content-id.
The library supports email scheduling, but since version 0.5.1 the scheduler is disabled by default. To enable email scheduling, the following property has to be provided:
spring.mail.scheduler.enabled=trueEmail can be set in different queues, from the one with highest priority to the least important. Priority 1 is the highest.
To define the number of priority levels to be used in the scheduler,
just add in the application.properties the following line:
spring.mail.scheduler.priorityLevels=5If not provided, by default 10 priority levels are considered.
Scheduling an email is actually easy and the SchedulerService allows to schedule an email with or without
the use of a template engine.
In order to schedule a plain text email, just create your service (or controller) where you autowire
the service SchedulerService and call a method scheduleEmail defined as in the following example
@Service
public void MyEmailSenderService {
@Autowired
private SchedulerService schedulerService;
public void scheduleEmail() throws CannotSendEmailException {
final Email mimeEmail = DefaultEmail.builder()
.from(new InternetAddress("[email protected]", "Gaius Iulius Caesar"))
.to(Lists.newArrayList(new InternetAddress(tyrannicida.getEmail(), tyrannicida.getName())))
.subject("Idus Martii")
.body("Sic semper...")
.encoding(Charset.forName("UTF-8"))
.build();
final OffsetDateTime scheduledDateTime = OffsetDateTime.now().plusDays(1);
final int priorityLevel = 1;
schedulerService.schedule(mimeEmail, scheduledDateTime, priorityLevel);
}
}Here we go, by calling schedulerEmail() an email has been scheduled to be sent after one day.
When scheduling emails, observe that OffsetDateTime must be used with UTC, so do not forget to convert it if you
use a different zone offset.
To schedule an email with a template and inline images, just call a new method called scheduleEmailWithTemplate()
@Service
public void MyEmailWithTemplateSenderService {
@Autowired
private SchedulerService schedulerService;
public void scheduleEmailWithTemplate() throws CannotSendEmailException {
final Email mimeEmail = DefaultEmail.builder()
.from(new InternetAddress("[email protected]", "Gaius Iulius Caesar"))
.to(Lists.newArrayList(new InternetAddress(tyrannicida.getEmail(), tyrannicida.getName())))
.subject("Idus Martii")
.body("")//Empty body
.encoding(Charset.forName("UTF-8"))
.build();
//Defining the model object for the given Freemarker template
final Map<String, Object> modelObject = new HashMap<>();
final File imageFile = //load your picture here, e.g. "my_image.jpg"
modelObject.put("tyrannicida", tyrannicida.getName());
final InlinePicture inlinePicture = DefaultInlinePicture.builder()
.file(imageFile)
.imageType(ImageType.JPG)
.templateName("my_image.jpg").build());
final OffsetDateTime scheduledDateTime = OffsetDateTime.now().plusDays(1);
final int priorityLevel = 1;
schedulerService.schedule(mimeEmail, scheduledDateTime, priorityLevel,
"idus_martii.ftl", modelObject, inlinePicture);
}
}Persistence has been introduced in version 0.5.1. Persistence is mainly of interest if the scheduler is used, therefore
it can be enabled only if the scheduler is enabled.
The persistence layer is optional, thus needs to be activated. The default implementation is fully based on embedded REDIS.
To enable the default persistence layer just add the additional properties in your application.properties file:
spring.mail.scheduler.persistence.enabled=true
spring.mail.scheduler.persistence.redis.enabled=true
spring.mail.scheduler.persistence.redis.embedded=true
spring.mail.scheduler.persistence.redis.host=localhost
spring.mail.scheduler.persistence.redis.port=6381
spring.mail.scheduler.persistence.redis.settings=I recommend to specify in the REDIS settings at least the appendfilename and dir properties,
so that you know where the append file is placed and which name it uses. For instance do:
spring.mail.scheduler.persistence.redis.settings=appendfilename email_appendonly.aof, dir /Users/your_username/DownloadsBy default we have the setting appendonly yes and appendfsync everysec. Feel free to override them or fine tune them
according with your needs.
Clearly, you can provide your own persistence layer by implementing the PersistenceService interface. You can also
use your REDIS implementation, but this will require extra coding on your side.
Observe that the persistence layer makes the emails being stored to be reloaded on application startup if not yet sent. In particular, the emails are loaded when scheduler is constructed.
###Impact of the Persistence layer on the default priority-based scheduler
The default scheduler is PriorityQueueSchedulerService, which by default stores everything in memory. Clerarly, having
thousands email being scheduled, storing everything in memory could drive to a potential OutOfMemoryException.
Enabling the persistence layer should allow to use REDIS for persisting scheduled emails. Anyway, you may want to
customize the behavior of the scheduler when interacting with the persistence layer, you can use the following params:
spring.mail.scheduler.persistence.desiredBatchSize=200
spring.mail.scheduler.persistence.minKeptInMemory=100
spring.mail.scheduler.persistence.maxKeptInMemory=1000The first defines the maximum amount of emails being loaded from the persistence layer when a slot is available in the priority queues; the second amount is the wish for the minimum amount of emails available in memory: the third defines the amount of emails to be kept in memory. Clearly, these two values impact the response time of the scheduler. The less you store in memory, the more it takes to send the next email. The smaller is the batch size, the higher the times you interact with the persistence layer.
Here are listed the backlog for the features to be added to the library in the near future:
- Optimizations for scheduled emails that require the use of a template engine.
- Add a listener to notify for the sending of an email.
- More examples.
Any contribution is welcome (and warmly encouraged).
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
==============================================
