---
name: spring-mail
description: |
Spring Mail for sending emails in Spring Boot 3.x. Covers JavaMailSender,
SimpleMailMessage, MimeMessage, HTML emails, attachments, templates
(Thymeleaf/FreeMarker), async sending, and testing.
USE WHEN: user mentions "spring mail", "JavaMailSender", "email Spring Boot",
"send email", "MimeMessage", "email templates", "SMTP Spring"
DO NOT USE FOR: transactional email services (SendGrid, SES) - use their SDKs,
SMS/push notifications - use appropriate services
allowed-tools: Read, Grep, Glob, Write, Edit
---
# Spring Mail
## Quick Start
```yaml
# application.yml
spring:
mail:
host: smtp.gmail.com
port: 587
username: ${MAIL_USERNAME}
password: ${MAIL_PASSWORD}
properties:
mail:
smtp:
auth: true
starttls:
enable: true
```
```java
@Service
@RequiredArgsConstructor
public class EmailService {
private final JavaMailSender mailSender;
public void sendSimpleEmail(String to, String subject, String text) {
SimpleMailMessage message = new SimpleMailMessage();
message.setTo(to);
message.setSubject(subject);
message.setText(text);
message.setFrom("noreply@example.com");
mailSender.send(message);
}
}
```
---
## Configuration
```java
@Configuration
public class MailConfig {
@Bean
public JavaMailSender javaMailSender(MailProperties props) {
JavaMailSenderImpl mailSender = new JavaMailSenderImpl();
mailSender.setHost(props.getHost());
mailSender.setPort(props.getPort());
mailSender.setUsername(props.getUsername());
mailSender.setPassword(props.getPassword());
Properties javaMailProperties = new Properties();
javaMailProperties.put("mail.smtp.auth", true);
javaMailProperties.put("mail.smtp.starttls.enable", true);
javaMailProperties.put("mail.smtp.connectiontimeout", 5000);
javaMailProperties.put("mail.smtp.timeout", 5000);
javaMailProperties.put("mail.smtp.writetimeout", 5000);
mailSender.setJavaMailProperties(javaMailProperties);
return mailSender;
}
}
```
---
## MimeMessage (HTML & Attachments)
```java
@Service
@RequiredArgsConstructor
@Slf4j
public class EmailService {
private final JavaMailSender mailSender;
// HTML Email
public void sendHtmlEmail(String to, String subject, String htmlContent)
throws MessagingException {
MimeMessage message = mailSender.createMimeMessage();
MimeMessageHelper helper = new MimeMessageHelper(message, true, "UTF-8");
helper.setTo(to);
helper.setSubject(subject);
helper.setText(htmlContent, true); // true = HTML
helper.setFrom("noreply@example.com");
mailSender.send(message);
}
// Email con attachment
public void sendEmailWithAttachment(String to, String subject, String text,
String attachmentPath) throws MessagingException {
MimeMessage message = mailSender.createMimeMessage();
MimeMessageHelper helper = new MimeMessageHelper(message, true);
helper.setTo(to);
helper.setSubject(subject);
helper.setText(text);
helper.setFrom("noreply@example.com");
FileSystemResource file = new FileSystemResource(new File(attachmentPath));
helper.addAttachment(file.getFilename(), file);
mailSender.send(message);
}
// Email con inline image
public void sendEmailWithInlineImage(String to, String subject,
String htmlContent, String imagePath)
throws MessagingException {
MimeMessage message = mailSender.createMimeMessage();
MimeMessageHelper helper = new MimeMessageHelper(message, true);
helper.setTo(to);
helper.setSubject(subject);
// Reference:
helper.setText(htmlContent, true);
helper.setFrom("noreply@example.com");
FileSystemResource image = new FileSystemResource(new File(imagePath));
helper.addInline("logo", image);
mailSender.send(message);
}
// Multiple recipients
public void sendToMultiple(String[] to, String[] cc, String[] bcc,
String subject, String text) throws MessagingException {
MimeMessage message = mailSender.createMimeMessage();
MimeMessageHelper helper = new MimeMessageHelper(message);
helper.setTo(to);
if (cc != null) helper.setCc(cc);
if (bcc != null) helper.setBcc(bcc);
helper.setSubject(subject);
helper.setText(text);
helper.setFrom("noreply@example.com");
mailSender.send(message);
}
}
```
---
## Thymeleaf Templates
```java
@Service
@RequiredArgsConstructor
public class TemplateEmailService {
private final JavaMailSender mailSender;
private final TemplateEngine templateEngine;
public void sendWelcomeEmail(String to, String userName) throws MessagingException {
Context context = new Context();
context.setVariable("userName", userName);
context.setVariable("activationLink", "https://example.com/activate/123");
String htmlContent = templateEngine.process("email/welcome", context);
MimeMessage message = mailSender.createMimeMessage();
MimeMessageHelper helper = new MimeMessageHelper(message, true, "UTF-8");
helper.setTo(to);
helper.setSubject("Welcome to Our Platform!");
helper.setText(htmlContent, true);
helper.setFrom("noreply@example.com");
mailSender.send(message);
}
public void sendOrderConfirmation(String to, Order order) throws MessagingException {
Context context = new Context();
context.setVariable("order", order);
context.setVariable("items", order.getItems());
context.setVariable("total", order.getTotal());
String htmlContent = templateEngine.process("email/order-confirmation", context);
MimeMessage message = mailSender.createMimeMessage();
MimeMessageHelper helper = new MimeMessageHelper(message, true, "UTF-8");
helper.setTo(to);
helper.setSubject("Order Confirmation #" + order.getId());
helper.setText(htmlContent, true);
helper.setFrom("orders@example.com");
mailSender.send(message);
}
}
```
```html
Thank you for joining our platform.
Please click the button below to activate your account:
Activate AccountWorld
" ); MimeMessage[] messages = greenMail.getReceivedMessages(); assertThat(messages).hasSize(1); String content = GreenMailUtil.getBody(messages[0]); assertThat(content).contains("