Introduction
JavaMail API (now part of Jakarta Mail) provides a platform-independent and protocol-independent framework for building mail and messaging applications. It supports SMTP, POP3, and IMAP protocols for sending and receiving emails.
Maven Dependencies
<!-- Jakarta Mail API --> <dependency> <groupId>com.sun.mail</groupId> <artifactId>jakarta.mail</artifactId> <version>2.0.1</version> </dependency> <!-- For Spring Boot projects --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-mail</artifactId> </dependency> <!-- For testing --> <dependency> <groupId>com.icegreen</groupId> <artifactId>greenmail</artifactId> <version>1.6.11</version> <scope>test</scope> </dependency>
Basic Email Setup
Simple Email Sending
import jakarta.mail.*;
import jakarta.mail.internet.*;
import java.util.Properties;
public class BasicEmailSender {
private final String host;
private final int port;
private final String username;
private final String password;
private final boolean auth;
private final boolean starttls;
public BasicEmailSender(String host, int port, String username,
String password, boolean auth, boolean starttls) {
this.host = host;
this.port = port;
this.username = username;
this.password = password;
this.auth = auth;
this.starttls = starttls;
}
public void sendSimpleEmail(String to, String subject, String content)
throws MessagingException {
// Setup mail server properties
Properties props = new Properties();
props.put("mail.smtp.host", host);
props.put("mail.smtp.port", port);
props.put("mail.smtp.auth", String.valueOf(auth));
props.put("mail.smtp.starttls.enable", String.valueOf(starttls));
// Create session with authentication
Session session = Session.getInstance(props, new Authenticator() {
@Override
protected PasswordAuthentication getPasswordAuthentication() {
return new PasswordAuthentication(username, password);
}
});
try {
// Create message
Message message = new MimeMessage(session);
message.setFrom(new InternetAddress(username));
message.setRecipients(Message.RecipientType.TO,
InternetAddress.parse(to));
message.setSubject(subject);
message.setText(content);
// Send message
Transport.send(message);
System.out.println("Email sent successfully to: " + to);
} catch (MessagingException e) {
System.err.println("Failed to send email: " + e.getMessage());
throw e;
}
}
// Usage example
public static void main(String[] args) {
BasicEmailSender sender = new BasicEmailSender(
"smtp.gmail.com", 587, "[email protected]",
"your-app-password", true, true);
try {
sender.sendSimpleEmail(
"[email protected]",
"Test Email Subject",
"This is a test email content."
);
} catch (MessagingException e) {
e.printStackTrace();
}
}
}
Advanced Email Features
HTML Email with Attachments
public class AdvancedEmailSender {
private Session session;
public AdvancedEmailSender(String host, int port, String username,
String password, boolean useTLS) {
Properties props = new Properties();
props.put("mail.smtp.host", host);
props.put("mail.smtp.port", port);
props.put("mail.smtp.auth", "true");
props.put("mail.smtp.starttls.enable", String.valueOf(useTLS));
this.session = Session.getInstance(props, new Authenticator() {
@Override
protected PasswordAuthentication getPasswordAuthentication() {
return new PasswordAuthentication(username, password);
}
});
// Enable debug mode for troubleshooting
session.setDebug(true);
}
public void sendHtmlEmail(String to, String subject, String htmlContent)
throws MessagingException {
Message message = new MimeMessage(session);
message.setFrom(new InternetAddress(session.getProperty("mail.smtp.user")));
message.setRecipients(Message.RecipientType.TO, InternetAddress.parse(to));
message.setSubject(subject);
// Set HTML content
message.setContent(htmlContent, "text/html; charset=utf-8");
Transport.send(message);
}
public void sendEmailWithAttachment(String to, String subject, String content,
File attachment) throws MessagingException {
Message message = new MimeMessage(session);
message.setFrom(new InternetAddress(session.getProperty("mail.smtp.user")));
message.setRecipients(Message.RecipientType.TO, InternetAddress.parse(to));
message.setSubject(subject);
// Create multipart message
Multipart multipart = new MimeMultipart();
// Text part
BodyPart messageBodyPart = new MimeBodyPart();
messageBodyPart.setText(content);
multipart.addBodyPart(messageBodyPart);
// Attachment part
messageBodyPart = new MimeBodyPart();
DataSource source = new FileDataSource(attachment);
messageBodyPart.setDataHandler(new DataHandler(source));
messageBodyPart.setFileName(attachment.getName());
multipart.addBodyPart(messageBodyPart);
message.setContent(multipart);
Transport.send(message);
}
public void sendEmailWithMultipleAttachments(String to, String subject,
String content, List<File> attachments)
throws MessagingException {
Message message = new MimeMessage(session);
message.setFrom(new InternetAddress(session.getProperty("mail.smtp.user")));
message.setRecipients(Message.RecipientType.TO, InternetAddress.parse(to));
message.setSubject(subject);
Multipart multipart = new MimeMultipart();
// Text part
MimeBodyPart textPart = new MimeBodyPart();
textPart.setText(content);
multipart.addBodyPart(textPart);
// Add all attachments
for (File file : attachments) {
MimeBodyPart attachmentPart = new MimeBodyPart();
attachmentPart.attachFile(file);
multipart.addBodyPart(attachmentPart);
}
message.setContent(multipart);
Transport.send(message);
}
public void sendEmailWithInlineImages(String to, String subject, String htmlContent,
Map<String, File> inlineImages)
throws MessagingException {
Message message = new MimeMessage(session);
message.setFrom(new InternetAddress(session.getProperty("mail.smtp.user")));
message.setRecipients(Message.RecipientType.TO, InternetAddress.parse(to));
message.setSubject(subject);
Multipart multipart = new MimeMultipart("related");
// HTML part
BodyPart htmlPart = new MimeBodyPart();
htmlPart.setContent(htmlContent, "text/html; charset=utf-8");
multipart.addBodyPart(htmlPart);
// Inline images
for (Map.Entry<String, File> entry : inlineImages.entrySet()) {
BodyPart imagePart = new MimeBodyPart();
imagePart.setDataHandler(new DataHandler(new FileDataSource(entry.getValue())));
imagePart.setHeader("Content-ID", "<" + entry.getKey() + ">");
imagePart.setDisposition(MimeBodyPart.INLINE);
multipart.addBodyPart(imagePart);
}
message.setContent(multipart);
Transport.send(message);
}
}
Email Templates and Builder Pattern
Email Builder for Complex Emails
public class EmailBuilder {
private final Session session;
private String from;
private String[] to;
private String[] cc;
private String[] bcc;
private String subject;
private String textContent;
private String htmlContent;
private List<File> attachments;
private Map<String, File> inlineImages;
private Priority priority = Priority.NORMAL;
public enum Priority {
HIGH("1"), NORMAL("3"), LOW("5");
private final String value;
Priority(String value) {
this.value = value;
}
public String getValue() {
return value;
}
}
public EmailBuilder(Session session) {
this.session = session;
this.attachments = new ArrayList<>();
this.inlineImages = new HashMap<>();
}
public EmailBuilder from(String from) {
this.from = from;
return this;
}
public EmailBuilder to(String... to) {
this.to = to;
return this;
}
public EmailBuilder cc(String... cc) {
this.cc = cc;
return this;
}
public EmailBuilder bcc(String... bcc) {
this.bcc = bcc;
return this;
}
public EmailBuilder subject(String subject) {
this.subject = subject;
return this;
}
public EmailBuilder textContent(String textContent) {
this.textContent = textContent;
return this;
}
public EmailBuilder htmlContent(String htmlContent) {
this.htmlContent = htmlContent;
return this;
}
public EmailBuilder addAttachment(File file) {
this.attachments.add(file);
return this;
}
public EmailBuilder addInlineImage(String contentId, File image) {
this.inlineImages.put(contentId, image);
return this;
}
public EmailBuilder priority(Priority priority) {
this.priority = priority;
return this;
}
public void send() throws MessagingException {
Message message = new MimeMessage(session);
// Set basic headers
if (from != null) {
message.setFrom(new InternetAddress(from));
}
message.setRecipients(Message.RecipientType.TO, parseAddresses(to));
if (cc != null && cc.length > 0) {
message.setRecipients(Message.RecipientType.CC, parseAddresses(cc));
}
if (bcc != null && bcc.length > 0) {
message.setRecipients(Message.RecipientType.BCC, parseAddresses(bcc));
}
message.setSubject(subject);
message.setHeader("X-Priority", priority.getValue());
message.setSentDate(new Date());
// Build message content
message.setContent(buildContent());
Transport.send(message);
}
private Address[] parseAddresses(String[] addresses) throws AddressException {
if (addresses == null) return new Address[0];
List<Address> addressList = new ArrayList<>();
for (String address : addresses) {
addressList.add(new InternetAddress(address));
}
return addressList.toArray(new Address[0]);
}
private Multipart buildContent() throws MessagingException {
Multipart multipart = new MimeMultipart();
// Handle text and HTML content
if (textContent != null || htmlContent != null) {
MimeBodyPart contentPart = new MimeBodyPart();
if (htmlContent != null && textContent != null) {
// Both text and HTML - create alternative content
Multipart alternative = new MimeMultipart("alternative");
MimeBodyPart textPart = new MimeBodyPart();
textPart.setText(textContent);
alternative.addBodyPart(textPart);
MimeBodyPart htmlPart = new MimeBodyPart();
htmlPart.setContent(htmlContent, "text/html; charset=utf-8");
alternative.addBodyPart(htmlPart);
contentPart.setContent(alternative);
} else if (htmlContent != null) {
contentPart.setContent(htmlContent, "text/html; charset=utf-8");
} else {
contentPart.setText(textContent);
}
multipart.addBodyPart(contentPart);
}
// Add attachments
for (File attachment : attachments) {
MimeBodyPart attachmentPart = new MimeBodyPart();
attachmentPart.attachFile(attachment);
multipart.addBodyPart(attachmentPart);
}
// Add inline images
if (!inlineImages.isEmpty()) {
for (Map.Entry<String, File> entry : inlineImages.entrySet()) {
MimeBodyPart imagePart = new MimeBodyPart();
imagePart.setDataHandler(new DataHandler(new FileDataSource(entry.getValue())));
imagePart.setHeader("Content-ID", "<" + entry.getKey() + ">");
imagePart.setDisposition(MimeBodyPart.INLINE);
multipart.addBodyPart(imagePart);
}
}
return multipart;
}
}
Spring Boot Integration
Spring Boot Mail Configuration
@Configuration
@ConfigurationProperties(prefix = "spring.mail")
@Data
public class MailConfig {
private String host;
private int port;
private String username;
private String password;
private String protocol = "smtp";
private Properties properties = new Properties();
@Bean
public JavaMailSender javaMailSender() {
JavaMailSenderImpl mailSender = new JavaMailSenderImpl();
mailSender.setHost(host);
mailSender.setPort(port);
mailSender.setUsername(username);
mailSender.setPassword(password);
mailSender.setProtocol(protocol);
mailSender.setJavaMailProperties(properties);
return mailSender;
}
}
// application.yml
spring:
mail:
host: smtp.gmail.com
port: 587
username: [email protected]
password: your-app-password
protocol: smtp
properties:
mail:
smtp:
auth: true
starttls:
enable: true
connectiontimeout: 5000
timeout: 5000
writetimeout: 5000
Spring Service for Email Operations
@Service
@Slf4j
public class EmailService {
private final JavaMailSender mailSender;
private final TemplateEngine templateEngine; // Thymeleaf or FreeMarker
public EmailService(JavaMailSender mailSender, TemplateEngine templateEngine) {
this.mailSender = mailSender;
this.templateEngine = templateEngine;
}
public void sendSimpleMessage(String to, String subject, String text) {
SimpleMailMessage message = new SimpleMailMessage();
message.setTo(to);
message.setSubject(subject);
message.setText(text);
message.setFrom(mailSender.getUsername());
try {
mailSender.send(message);
log.info("Email sent successfully to: {}", to);
} catch (MailException e) {
log.error("Failed to send email to: {}", to, e);
throw new EmailException("Failed to send email", e);
}
}
public void sendMimeMessage(String to, String subject, String htmlContent) {
MimeMessage message = mailSender.createMimeMessage();
try {
MimeMessageHelper helper = new MimeMessageHelper(message, true, "UTF-8");
helper.setTo(to);
helper.setSubject(subject);
helper.setText(htmlContent, true);
helper.setFrom(mailSender.getUsername());
mailSender.send(message);
log.info("HTML email sent successfully to: {}", to);
} catch (MessagingException e) {
log.error("Failed to send MIME email to: {}", to, e);
throw new EmailException("Failed to send MIME email", e);
}
}
public void sendTemplatedEmail(String to, String subject, String templateName,
Map<String, Object> variables) {
try {
// Process template
String htmlContent = templateEngine.process(templateName,
new Context(Locale.getDefault(), variables));
sendMimeMessage(to, subject, htmlContent);
} catch (Exception e) {
log.error("Failed to send templated email to: {}", to, e);
throw new EmailException("Failed to send templated email", e);
}
}
public void sendMessageWithAttachment(String to, String subject, String text,
String attachmentPath) {
MimeMessage message = mailSender.createMimeMessage();
try {
MimeMessageHelper helper = new MimeMessageHelper(message, true);
helper.setTo(to);
helper.setSubject(subject);
helper.setText(text);
helper.setFrom(mailSender.getUsername());
// Add attachment
FileSystemResource file = new FileSystemResource(new File(attachmentPath));
helper.addAttachment(Objects.requireNonNull(file.getFilename()), file);
mailSender.send(message);
log.info("Email with attachment sent to: {}", to);
} catch (MessagingException e) {
log.error("Failed to send email with attachment to: {}", to, e);
throw new EmailException("Failed to send email with attachment", e);
}
}
public void sendBulkEmails(List<String> recipients, String subject,
String templateName, Map<String, Object> variables) {
for (String recipient : recipients) {
try {
sendTemplatedEmail(recipient, subject, templateName, variables);
// Small delay to avoid being flagged as spam
Thread.sleep(100);
} catch (Exception e) {
log.error("Failed to send bulk email to: {}", recipient, e);
// Continue with other emails even if one fails
}
}
}
}
// Custom exception
class EmailException extends RuntimeException {
public EmailException(String message) {
super(message);
}
public EmailException(String message, Throwable cause) {
super(message, cause);
}
}
Asynchronous Email Sending
Async Email Service
@Service
@Slf4j
public class AsyncEmailService {
private final JavaMailSender mailSender;
private final TaskExecutor taskExecutor;
public AsyncEmailService(JavaMailSender mailSender,
@Qualifier("taskExecutor") TaskExecutor taskExecutor) {
this.mailSender = mailSender;
this.taskExecutor = taskExecutor;
}
@Async
public CompletableFuture<Void> sendEmailAsync(String to, String subject, String text) {
return CompletableFuture.runAsync(() -> {
try {
SimpleMailMessage message = new SimpleMailMessage();
message.setTo(to);
message.setSubject(subject);
message.setText(text);
message.setFrom(mailSender.getUsername());
mailSender.send(message);
log.info("Async email sent successfully to: {}", to);
} catch (Exception e) {
log.error("Failed to send async email to: {}", to, e);
throw new EmailException("Failed to send async email", e);
}
}, taskExecutor);
}
public void sendEmailWithCallback(String to, String subject, String text) {
taskExecutor.execute(() -> {
try {
SimpleMailMessage message = new SimpleMailMessage();
message.setTo(to);
message.setSubject(subject);
message.setText(text);
message.setFrom(mailSender.getUsername());
mailSender.send(message);
log.info("Callback email sent successfully to: {}", to);
} catch (Exception e) {
log.error("Failed to send callback email to: {}", to, e);
}
});
}
}
// Configuration for async support
@Configuration
@EnableAsync
public class AsyncConfig {
@Bean("taskExecutor")
public TaskExecutor taskExecutor() {
ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
executor.setCorePoolSize(5);
executor.setMaxPoolSize(10);
executor.setQueueCapacity(25);
executor.setThreadNamePrefix("EmailExecutor-");
executor.initialize();
return executor;
}
}
Email Validation and Utilities
Email Validation Service
@Service
public class EmailValidationService {
private static final Pattern EMAIL_PATTERN =
Pattern.compile("^[A-Z0-9._%+-]+@[A-Z0-9.-]+\\.[A-Z]{2,6}$", Pattern.CASE_INSENSITIVE);
public boolean isValidEmail(String email) {
if (email == null || email.trim().isEmpty()) {
return false;
}
Matcher matcher = EMAIL_PATTERN.matcher(email);
return matcher.matches();
}
public List<String> validateEmailList(List<String> emails) {
return emails.stream()
.filter(this::isValidEmail)
.collect(Collectors.toList());
}
public void validateEmailOrThrow(String email) {
if (!isValidEmail(email)) {
throw new IllegalArgumentException("Invalid email address: " + email);
}
}
}
// Email utility class
@Component
public class EmailUtils {
public InternetAddress[] parseAddressList(String addresses) throws AddressException {
return InternetAddress.parse(addresses);
}
public String generateMessageId(String domain) {
return "<" + UUID.randomUUID() + "@" + domain + ">";
}
public Map<String, String> parseEmailHeaders(Message message) throws MessagingException {
Map<String, String> headers = new HashMap<>();
Enumeration<Header> allHeaders = message.getAllHeaders();
while (allHeaders.hasMoreElements()) {
Header header = allHeaders.nextElement();
headers.put(header.getName(), header.getValue());
}
return headers;
}
public void addCustomHeaders(Message message, Map<String, String> headers)
throws MessagingException {
for (Map.Entry<String, String> entry : headers.entrySet()) {
message.addHeader(entry.getKey(), entry.getValue());
}
}
}
Testing Email Functionality
Test Configuration with GreenMail
@SpringBootTest
@TestPropertySource(properties = {
"spring.mail.host=127.0.0.1",
"spring.mail.port=3025",
"spring.mail.username=test@localhost",
"spring.mail.password=test"
})
public class EmailServiceTest {
@Autowired
private EmailService emailService;
@RegisterExtension
static GreenMailExtension greenMail = new GreenMailExtension(ServerSetupTest.SMTP)
.withConfiguration(GreenMailConfiguration.aConfig().withUser("test", "test"))
.withPerMethodLifecycle(false);
@Test
public void testSendSimpleEmail() throws Exception {
// Given
String to = "[email protected]";
String subject = "Test Subject";
String text = "Test Content";
// When
emailService.sendSimpleMessage(to, subject, text);
// Then
await().atMost(2, TimeUnit.SECONDS).untilAsserted(() -> {
MimeMessage[] receivedMessages = greenMail.getReceivedMessages();
assertThat(receivedMessages).hasSize(1);
MimeMessage receivedMessage = receivedMessages[0];
assertThat(receivedMessage.getSubject()).isEqualTo(subject);
assertThat(receivedMessage.getAllRecipients()[0].toString()).isEqualTo(to);
});
}
@Test
public void testSendEmailWithAttachment() throws Exception {
// Given
String to = "[email protected]";
String subject = "Test Attachment";
String text = "Test Content with Attachment";
String attachmentPath = "test-file.txt";
// Create test file
Files.write(Paths.get(attachmentPath), "Test attachment content".getBytes());
// When
emailService.sendMessageWithAttachment(to, subject, text, attachmentPath);
// Then
await().atMost(2, TimeUnit.SECONDS).untilAsserted(() -> {
MimeMessage[] receivedMessages = greenMail.getReceivedMessages();
assertThat(receivedMessages).hasSize(1);
MimeMessage receivedMessage = receivedMessages[0];
assertThat(receivedMessage.getSubject()).isEqualTo(subject);
// Verify attachment
assertThat(receivedMessage.getContent()).isInstanceOf(MimeMultipart.class);
MimeMultipart multipart = (MimeMultipart) receivedMessage.getContent();
assertThat(multipart.getCount()).isGreaterThan(1);
});
// Cleanup
Files.deleteIfExists(Paths.get(attachmentPath));
}
}
// Unit test for validation
@Test
public void testEmailValidation() {
EmailValidationService validator = new EmailValidationService();
assertTrue(validator.isValidEmail("[email protected]"));
assertTrue(validator.isValidEmail("[email protected]"));
assertFalse(validator.isValidEmail("invalid-email"));
assertFalse(validator.isValidEmail(""));
assertFalse(validator.isValidEmail(null));
}
Best Practices and Production Considerations
Production-Ready Email Service
@Service
@Slf4j
public class ProductionEmailService {
private final JavaMailSender mailSender;
private final EmailValidationService validationService;
private final RetryTemplate retryTemplate;
public ProductionEmailService(JavaMailSender mailSender,
EmailValidationService validationService) {
this.mailSender = mailSender;
this.validationService = validationService;
this.retryTemplate = createRetryTemplate();
}
public EmailResult sendEmailWithRetry(EmailRequest request) {
try {
validationService.validateEmailOrThrow(request.getTo());
return retryTemplate.execute(context -> {
try {
sendEmailInternal(request);
return EmailResult.success(request.getTo());
} catch (Exception e) {
log.warn("Attempt {} failed for email to: {}",
context.getRetryCount(), request.getTo(), e);
if (context.getRetryCount() >= 2) {
return EmailResult.failure(request.getTo(), e.getMessage());
}
throw e;
}
});
} catch (Exception e) {
log.error("Failed to send email after retries to: {}", request.getTo(), e);
return EmailResult.failure(request.getTo(), e.getMessage());
}
}
private void sendEmailInternal(EmailRequest request) throws MessagingException {
MimeMessage message = mailSender.createMimeMessage();
MimeMessageHelper helper = new MimeMessageHelper(message, true, "UTF-8");
helper.setTo(request.getTo());
helper.setSubject(request.getSubject());
helper.setText(request.getContent(), request.isHtml());
helper.setFrom(mailSender.getUsername());
if (request.getCc() != null) {
helper.setCc(request.getCc());
}
if (request.getBcc() != null) {
helper.setBcc(request.getBcc());
}
// Add attachments
if (request.getAttachments() != null) {
for (EmailAttachment attachment : request.getAttachments()) {
helper.addAttachment(attachment.getFilename(),
new ByteArrayResource(attachment.getContent()));
}
}
mailSender.send(message);
}
private RetryTemplate createRetryTemplate() {
RetryTemplate template = new RetryTemplate();
ExponentialBackOffPolicy backOffPolicy = new ExponentialBackOffPolicy();
backOffPolicy.setInitialInterval(1000);
backOffPolicy.setMultiplier(2.0);
backOffPolicy.setMaxInterval(10000);
SimpleRetryPolicy retryPolicy = new SimpleRetryPolicy();
retryPolicy.setMaxAttempts(3);
template.setBackOffPolicy(backOffPolicy);
template.setRetryPolicy(retryPolicy);
return template;
}
// DTO classes
@Data
public static class EmailRequest {
private String to;
private String subject;
private String content;
private boolean html = false;
private String[] cc;
private String[] bcc;
private List<EmailAttachment> attachments;
}
@Data
public static class EmailAttachment {
private String filename;
private byte[] content;
private String contentType;
}
@Data
public static class EmailResult {
private final String recipient;
private final boolean success;
private final String errorMessage;
private final Instant timestamp;
public static EmailResult success(String recipient) {
return new EmailResult(recipient, true, null, Instant.now());
}
public static EmailResult failure(String recipient, String errorMessage) {
return new EmailResult(recipient, false, errorMessage, Instant.now());
}
}
}
Conclusion
JavaMail API provides comprehensive email functionality for Java applications. Key points to remember:
- Use Jakarta Mail for new projects (the successor to JavaMail)
- Configure proper SMTP settings including authentication and TLS
- Handle attachments and HTML content appropriately
- Implement error handling and retry mechanisms for production
- Use Spring Boot's mail support for easier configuration
- Test email functionality with tools like GreenMail
- Follow email best practices to avoid being flagged as spam
By following these patterns and best practices, you can build robust, production-ready email functionality in your Java applications.