By WebNest Studio Engineering Team
Spring Boot Tutorial
Sending Email with Spring Boot
Email is still the primary channel for account verification, password resets, receipts, notifications and newsletters. Spring Boot makes sending email straightforward with JavaMailSender, but production email also needs HTML templates, attachments, asynchronous sending, a safe local test setup, and good deliverability.
This lesson covers configuring SMTP (Gmail, Amazon SES, SendGrid, Mailgun), sending plain-text and HTML emails, rendering templates with Thymeleaf, adding attachments and inline images, testing locally with Mailpit, and practices that keep your emails out of spam folders.
Configuration
Add spring-boot-starter-mail and set spring.mail.host, port, username, password and the TLS properties. Spring Boot then auto-configures a JavaMailSender. For Gmail you must use an app password, not your account password; transactional email providers (Amazon SES, SendGrid, Mailgun, Postmark) are the better choice for production volume and deliverability.
Simple and MIME Messages
SimpleMailMessage covers plain-text emails. For HTML, attachments and inline images, create a MimeMessage and fill it with MimeMessageHelper in multipart mode. Always include a plain-text alternative alongside HTML; some clients and spam filters prefer it.
Templates
Building HTML in Java strings is unmaintainable. Use Thymeleaf's TemplateEngine to render templates/email/*.html with a Context of variables, then pass the rendered HTML to the helper. Email HTML should use simple table layouts and inline styles, because many clients ignore external CSS.
Asynchronous and Reliable Sending
SMTP calls take hundreds of milliseconds or more and can fail. Send from an @Async method or a message queue so user requests stay fast, send only after the database transaction commits (@TransactionalEventListener), and retry transient failures. For critical emails, record them in an outbox table and track delivery status.
Deliverability
Configure SPF, DKIM and DMARC DNS records for your sending domain, send from a consistent address on your own domain, include an unsubscribe link in marketing email, and never send from a no-reply@gmail.com-style address. Monitor bounces and complaints through your provider.
Examples
Configuration with Mailpit for local testing
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-mail</artifactId>
</dependency>
# compose.yaml — Mailpit catches all mail locally (web UI on http://localhost:8025)
services:
mailpit:
image: axllent/mailpit
ports:
- "1025:1025"
- "8025:8025"
# application.yml (development)
spring:
mail:
host: localhost
port: 1025
# application-prod.yml (e.g. Amazon SES SMTP)
spring:
mail:
host: email-smtp.ap-south-1.amazonaws.com
port: 587
username: ${SMTP_USER}
password: ${SMTP_PASSWORD}
properties:
mail.smtp.auth: true
mail.smtp.starttls.enable: true
mail.smtp.connectiontimeout: 5000
mail.smtp.timeout: 5000
(Every email sent in development appears in the Mailpit inbox at http://localhost:8025 — nothing reaches real users.)
Plain text and HTML emails with an attachment
@Service
public class MailService {
private final JavaMailSender mailSender;
public MailService(JavaMailSender mailSender) {
this.mailSender = mailSender;
}
public void sendPlain(String to, String subject, String text) {
SimpleMailMessage msg = new SimpleMailMessage();
msg.setFrom("Webnest Studio <hello@webneststudio.co.in>");
msg.setTo(to);
msg.setSubject(subject);
msg.setText(text);
mailSender.send(msg);
}
public void sendInvoice(String to, String orderId, String html, byte[] pdf) throws MessagingException {
MimeMessage message = mailSender.createMimeMessage();
MimeMessageHelper helper = new MimeMessageHelper(message, true, "UTF-8"); // multipart
helper.setFrom("Webnest Studio <billing@webneststudio.co.in>");
helper.setTo(to);
helper.setSubject("Your invoice for order " + orderId);
helper.setText("Your invoice is attached.", html); // plain-text + HTML alternatives
helper.addInline("logo", new ClassPathResource("static/img/logo.png"));
helper.addAttachment("invoice-" + orderId + ".pdf", new ByteArrayResource(pdf), "application/pdf");
mailSender.send(message);
}
}
Mailpit inbox:
From: Webnest Studio <billing@webneststudio.co.in>
Subject: Your invoice for order WN-10231
Attachments: invoice-WN-10231.pdf (48 KB), inline logo.png
Thymeleaf email templates sent asynchronously after commit
<!-- templates/email/welcome.html -->
<html xmlns:th="http://www.thymeleaf.org">
<body style="font-family: Arial, sans-serif">
<table width="600" cellpadding="16">
<tr><td>
<h2 th:text="|Welcome, ${name}!|">Welcome!</h2>
<p>Your first course is ready:</p>
<a th:href="${courseUrl}" style="background:#d4a017;color:#000;padding:10px 16px;text-decoration:none">
Start learning
</a>
</td></tr>
</table>
</body>
</html>
@Component
public class WelcomeEmailListener {
private final JavaMailSender mailSender;
private final SpringTemplateEngine templates;
public WelcomeEmailListener(JavaMailSender mailSender, SpringTemplateEngine templates) {
this.mailSender = mailSender;
this.templates = templates;
}
@Async
@TransactionalEventListener
public void onRegistered(UserRegisteredEvent e) throws MessagingException {
Context ctx = new Context(Locale.ENGLISH);
ctx.setVariable("name", e.name());
ctx.setVariable("courseUrl", "https://www.webneststudio.co.in/learn/java-core");
String html = templates.process("email/welcome", ctx);
MimeMessage message = mailSender.createMimeMessage();
MimeMessageHelper helper = new MimeMessageHelper(message, true, "UTF-8");
helper.setTo(e.email());
helper.setSubject("Welcome to Webnest Studio");
helper.setText("Welcome, " + e.name() + "! Start learning: https://www.webneststudio.co.in/learn", html);
mailSender.send(message);
}
}
POST /api/auth/register -> 201 in 38 ms
(after commit, on task-3) welcome email rendered and sent to asha@webnest.in
Common Mistakes
- Sending email synchronously inside the request, making sign-up slow and failing it when SMTP is down.
- Sending emails inside a transaction that may roll back, so users receive emails for actions that never happened.
- Hard-coding SMTP passwords in application.yml.
- Using a real SMTP server during development and accidentally emailing real customers; use Mailpit.
- Sending HTML only without a plain-text part and without SPF/DKIM, hurting deliverability.
Exercise
A teammate is about to make this mistake: Sending email synchronously inside the request, making sign-up slow and failing it when SMTP is down. Use Configuration to review the decision. Write a corrected implementation or design sketch that follows spring-boot-starter-mail auto-configures JavaMailSender from spring.mail.* properties., then name one edge case you would check.
Show hints
- Start with Configuration and compare your approach with Configuration with Mailpit for local testing. Identify the decision or behavior the lesson recommends.
- Walk through your scenario step by step. Confirm that it follows spring-boot-starter-mail auto-configures JavaMailSender from spring.mail.* properties. and that it would catch the failure described by Sending email synchronously inside the request, making sign-up slow and failing it when SMTP is down..
Quick quiz
1. Which choice best describes the recommended approach in Sending Email with Spring Boot?
- A. Sending email synchronously inside the request, making sign-up slow and failing it when SMTP is down.
- B. Sending emails inside a transaction that may roll back, so users receive emails for actions that never happened.
- C. spring-boot-starter-mail auto-configures JavaMailSender from spring.mail.* properties.
Show answer
C. This is the recommended approach: spring-boot-starter-mail auto-configures JavaMailSender from spring.mail.* properties. Avoid: Sending email synchronously inside the request, making sign-up slow and failing it when SMTP is down.
Interview questions
Why does this principle matter in Sending Email with Spring Boot: spring-boot-starter-mail auto-configures JavaMailSender from spring.mail.* properties.
Show answer
spring-boot-starter-mail auto-configures JavaMailSender from spring.mail.* properties. Apply this in Configuration; the example Configuration with Mailpit for local testing shows one way to do it. Avoid Sending email synchronously inside the request, making sign-up slow and failing it when SMTP is down. and explain how your implementation or design prevents that failure.
Key Points to Remember
- spring-boot-starter-mail auto-configures JavaMailSender from spring.mail.* properties.
- Use SimpleMailMessage for text; MimeMessageHelper for HTML, attachments and inline images.
- Render HTML emails with Thymeleaf templates and include a plain-text alternative.
- Send asynchronously and after commit; retry transient failures.
- Test with Mailpit locally and configure SPF, DKIM and DMARC in production.
Practice in the playground
Write and run your own code for this topic, or start from the exercise or an example. Runs plain Java 17. Frameworks such as Spring, and databases, are not available here. Your code for each topic is kept in this browser.
Run the examples
Change an input, predict the result, then compare it with the output. Explain why the result changes.
These examples need a JDK project with their libraries on your computer, so they can be copied but not run here. Codelab runs Python, FastAPI backends with SQLite, plain Java 17 and HTML/CSS/JavaScript.
Written by
WebNest Studio Engineering Team
Practical lessons from developers working with Java, Python, React, databases and production systems.
Led by Vansh Duggal, Founder, WebNest Studio · Full-stack & software engineering