What it is
Jakarta Mail (formerly JavaMail) is a Java API for sending, receiving, and managing email messages using protocols such as SMTP, IMAP, and POP3. It provides a simple interface for building email applications and integrating email functionality into Java applications.
Jakarta Mail allows sending emails via SMTP, reading emails from IMAP or POP3, handling attachments, multipart messages, HTML content, and managing folders. It integrates easily with Java SE and Jakarta EE applications.
Installation
Add dependency in pom.xml:
<dependency>
<groupId>com.sun.mail</groupId>
<artifactId>jakarta.mail</artifactId>
<version>2.1.2</version>
</dependency>Getting started
The smallest useful thing you can do with it, and what each part means.
import jakarta.mail.*;
import jakarta.mail.internet.*;
import java.util.Properties;
Properties props = new Properties();
props.put("mail.smtp.host", "smtp.example.com");
props.put("mail.smtp.port", "587");
props.put("mail.smtp.auth", "true");
Session session = Session.getInstance(props, new Authenticator() {
protected PasswordAuthentication getPasswordAuthentication() {
return new PasswordAuthentication("username", "password");
}
});
Message message = new MimeMessage(session);
message.setFrom(new InternetAddress("from@example.com"));
message.setRecipients(Message.RecipientType.TO, InternetAddress.parse("to@example.com"));
message.setSubject("Test Email");
message.setText("Hello, this is a test email.");
Transport.send(message);Properties props = new Properties();
props.put("mail.store.protocol", "imap");
Session session = Session.getDefaultInstance(props, null);
Store store = session.getStore("imap");
store.connect("imap.example.com", "username", "password");
Folder inbox = store.getFolder("INBOX");
inbox.open(Folder.READ_ONLY);
Message[] messages = inbox.getMessages();
for (Message msg : messages) {
System.out.println(msg.getSubject());
}
inbox.close(false);
store.close();Advanced usage
Where the library earns its place over a simpler alternative.
MimeMessage message = new MimeMessage(session);
message.setFrom(new InternetAddress("from@example.com"));
message.setRecipients(Message.RecipientType.TO, InternetAddress.parse("to@example.com"));
message.setSubject("HTML Email");
message.setContent("<h1>Hello</h1><p>This is an HTML email</p>", "text/html");
Transport.send(message);MimeBodyPart textPart = new MimeBodyPart();
textPart.setText("Please find the attachment.");
MimeBodyPart attachmentPart = new MimeBodyPart();
attachmentPart.attachFile(new File("file.pdf"));
Multipart multipart = new MimeMultipart();
multipart.addBodyPart(textPart);
multipart.addBodyPart(attachmentPart);
MimeMessage message = new MimeMessage(session);
message.setFrom(new InternetAddress("from@example.com"));
message.setRecipients(Message.RecipientType.TO, InternetAddress.parse("to@example.com"));
message.setSubject("Email with Attachment");
message.setContent(multipart);
Transport.send(message);Folder inbox = store.getFolder("INBOX");
inbox.open(Folder.READ_WRITE);
for (Message msg : inbox.getMessages()) {
if (!msg.isSet(Flags.Flag.SEEN)) {
System.out.println("Unread: " + msg.getSubject());
msg.setFlag(Flags.Flag.SEEN, true);
}
}
inbox.close(true);Errors and fixes
The failures you are most likely to hit, and what actually resolves them.
- AuthenticationFailedException
- Occurs if username or password is incorrect. Check credentials and server settings.
- SendFailedException
- Occurs when the email cannot be delivered. Verify recipients and SMTP server configuration.
- MessagingException
- Generic error for email operations. Inspect cause for details.
Best practices
- Use SSL/TLS for secure email transmission.
- Reuse Session objects instead of creating new ones repeatedly.
- Handle exceptions like MessagingException and IOException gracefully.
- Close connections, folders, and stores properly to avoid resource leaks.
- Validate email addresses before sending to prevent delivery failures.
Background
Why it exists, and what it was reacting to.
JavaMail was originally developed as part of the Java EE platform and later moved to the Eclipse Foundation under Jakarta EE. It abstracts the complexities of email protocols, allowing developers to focus on application logic. Jakarta Mail is widely used in enterprise applications, automated email notifications, and email clients.