Jakarta Mail Tutorial

The Jakarta Mail API offers a robust framework for creating email messaging applications using the popular Java programming language. With the API, you can send and receive emails via Simple Mail Transfer Protocol (SMTP), Internet Message Access Protocol (IMAP), or Post Office Protocol (POP).

What is Jakarta Mail?

For a long time, the Java Enterprise Edition (commonly known as Java EE), has been the de facto platform for developing mission-critical applications. 

Recently, in order to stir the creation of cloud-native applications, several prominent software vendors joined hands to transfer Java EE technologies to the Eclipse Foundation, which is a not-for-profit organization tasked with stewarding the activities of the Eclipse open source software community.

Consequently, the Java EE has been rebranded to Jakarta EE. Notably, as of July 2018, the mail package that was known as JavaMail API, has been further enhanced by the Eclipse Foundation and renamed to Jakarta Mail

In spite of the name change, all the main classes and properties definitions still remain the same for both Jakarta Mail and JavaMail.

In this article, we’re going to illustrate how to utilize the Jakarta Mail project to send different types of email messages. 

Getting started with Jakarta Mail

To get started using Jakarta Mail, you can download the jakarta.mail.jar file available on the Jakarta Mail project website. Then, you should set your CLASSPATH environment variable to consist of the downloaded “jakarta.mail.jar” file and the current directory.

For example, in a Windows machine, if you have downloaded the file to the /you/you/download/ directory, the following would work:

      set CLASSPATH=%CLASSPATH%;c:\download\jakarta.mail.jar;.

Besides, since the Jakarta Mail jar files are available on the Maven repository, you can specify the following Maven dependency and add them to your work environment.

com.sun.mailjakarta.mail1.6.4

Jakarta Mail API Core Classes

The Jakarta Mail API has a wide range of classes and interfaces that can be used for sending, reading, and performing other actions with email messages—just like in a typical mailing system.

Although there are several packages in the Jakarta Mail Project, two of the most frequently used ones are javax.mail and javax.mail.internet. 

The javax.mail package provides classes that model a mail system and the javax.mail.internet package provides classes that that are focused to Internet mail systems.

Here is a description of the core classes in each of the packages:

1. javax.mail.Session

The Session class, which is not subclassed, is the top-level class of the Jakarta Mail API. It’s a multi-threaded object that acts as the connection factory for the Jakarta Mail API—apart from collecting the mail API’s properties and defaults, it is responsible for configuration settings and authentication.

To get the Session object, you can call either of the following two methods:

  • getDefaultInstance(), which returns the default session
  • getInstance(), which returns a new session

2. javax.mail.Message

The Message class is an abstract class that models an email message; its subclasses support the actual implementations. Usually, its MimeMessage subclass (javax.mail.internet.MimeMessage) is used for actually crafting the details of the email message to be sent. A MimeMessage is an email message that uses the MIME (Multipurpose Internet Mail Extension) formatting style.

Here are some of the commonly used methods of the MimeMessage class:

  • setFrom(Address addresses)—it’s used to set the “From” header field.
  • setRecipients(Message.RecipientType type, String addresses)—it’s used to set the stated recipient type to the provided addresses. The possible defined address types are “TO” (Message.RecipientType.TO), “CC” (Message.RecipientType.CC), and “BCC” (Message.RecipientType.BCC).
  • setSubject(String subject)—it’s used to set the email’s subject header field.
  • setText(String text)—it’s used to set the provided String as the email’s content, using MIME type of “text/plain”.
  • setContent(Object message, String contentType)—it’s used to set the email’s content, using MIME type of “text/html”.

3. javax.mail.Address

The Address class is an abstract class that models the addresses (To and From addresses) in an email message; its subclasses support the actual implementations. Usually, its javax.mail.internet.InternetAddress subclass, which denotes an Internet email address, is commonly used.

4. javax.mail.Authenticator

The Authenticator class is an abstract class that is used to get authentication to access the mail server resources—often by requiring the user’s information. Usually, its PasswordAuthentication subclass is commonly used. 

5. javax.mail.Transport

The Transport class is an abstract class that uses the SMTP protocol for submitting and transporting email messages.

How to send an email in Jakarta Mail

After illustrating the main classes in the Jakarta Mail Project, let’s now see how to implement them to send a simple email message via an SMTP server.

Essentially, here are the steps for sending an email message using the Jakarta Mail API:

  • Configure the SMTP server details using the Java Properties object. For this demonstration, we’ll use Mailtrap to set up our SMTP server. Mailtrap is a simple tool that provides a fake SMTP server for testing, reviewing, and analyzing email functionalities during development. You can visit the Mailtrap’s website to open an account and get your free SMTP server details. Or, you can also get SMTP server details from any other email service provider. 
  • Create a Session object by calling the getInstance() method. Then, pass the Mailtrap’s username and password to PasswordAuthentication. When creating the session object, you should always register the Authenticator with the Session
  • Once the Session object is created, the next step is to create the email message to be sent. To do this, start by passing the created session object in the MimeMessage class constructor.
  • Next, after creating the message object, set the From, To, and Subject fields for the email message.
  • Use the setText() method to set the content of the email message. 
  • Use the Transport object to send the email message.
  • Add Exceptions to retrieve the details of any possible errors when sending the message.

Here is the code for using the Jakarta Mail API for sending email messages:

package jakartaemail;


import java.util.Properties;

import javax.mail.Message;
import javax.mail.MessagingException;
import javax.mail.PasswordAuthentication;
import javax.mail.Session;
import javax.mail.Transport;
import javax.mail.internet.InternetAddress;
import javax.mail.internet.MimeMessage;

public class JakartaEmail {
   public static void main(String[] args) {
      //provide recipient's email ID
      String to = "jakartato@example.com";

      //provide sender's email ID
      String from = "jakartafrom@example.com";
      //provide Mailtrap's username
      final String username = "a094ccae2cfdb3";
      //provide Mailtrap's password
      final String password = "82a851fcf4aa33";

      //provide Mailtrap's host address 
      String host = "smtp.mailtrap.io";
      //configure Mailtrap's SMTP server details 
      Properties props = new Properties();
      props.put("mail.smtp.auth", "true");
      props.put("mail.smtp.starttls.enable", "true");  
      props.put("mail.smtp.host", host);
      props.put("mail.smtp.port", "587");

      //create the Session object
      Session session = Session.getInstance(props,
         new javax.mail.Authenticator() {
            protected PasswordAuthentication getPasswordAuthentication() {
               return new PasswordAuthentication(username, password);
    }
         });

      try {
    //create a MimeMessage object
    Message message = new MimeMessage(session);
 
    //set From email field 
    message.setFrom(new InternetAddress(from));
 
    //set To email field
    message.setRecipients(Message.RecipientType.TO,
               InternetAddress.parse(to));
 
    //set email subject field
    message.setSubject("Here comes Jakarta Mail!");
 
    //set the content of the email message
    message.setText("Just discovered that Jakarta Mail is fun and easy to use");

    //send the email message
    Transport.send(message);

    System.out.println("Email Message Sent Successfully");

      } catch (MessagingException e) {
         throw new RuntimeException(e);
      }
   }
}

If we compile and run the above code, and open our Mailtrap inbox, here’s the output we get:

It worked!

Sending HTML email in Jakarta Mail

While the process of sending an HTML email using the Jakarta Mail Project is mostly the same as sending a simple email message, the only difference is that here, instead of the setText() method,  we’ll be using the setContent() method to set content and specify “text/html” in the second argument, indicating the message has HTML content.

Here is the code:

package jakartaemail;


import java.util.Properties;

import javax.mail.Message;
import javax.mail.MessagingException;
import javax.mail.PasswordAuthentication;
import javax.mail.Session;
import javax.mail.Transport;
import javax.mail.internet.InternetAddress;
import javax.mail.internet.MimeMessage;

public class JakartaEmail {
   public static void main(String[] args) {
      //provide recipient's email ID
      String to = "jakartato@example.com";

      //provide sender's email ID
      String from = "jakartafrom@example.com";
      //provide Mailtrap's username
      final String username = "a094ccae2cfdb3";
      //provide Mailtrap's password
      final String password = "82a851fcf4aa33";

      //provide Mailtrap's host address 
      String host = "smtp.mailtrap.io";
      //configure Mailtrap's SMTP server details 
      Properties props = new Properties();
      props.put("mail.smtp.auth", "true");
      props.put("mail.smtp.starttls.enable", "true");  
      props.put("mail.smtp.host", host);
      props.put("mail.smtp.port", "587");

      //create the Session object
      Session session = Session.getInstance(props,
         new javax.mail.Authenticator() {
            protected PasswordAuthentication getPasswordAuthentication() {
               return new PasswordAuthentication(username, password);
    }
         });

      try {
    //create a MimeMessage object
    Message message = new MimeMessage(session);
 
    //set From email field 
    message.setFrom(new InternetAddress(from));
 
    //set To email field
    message.setRecipients(Message.RecipientType.TO,
               InternetAddress.parse(to));
 
    //set email subject field
    message.setSubject("Here comes Jakarta Mail!");
 
    //set the content of the email message
    message.setContent("Just discovered that Jakarta Mail is fun and easy to use", "text/html");

    //send the email message
    Transport.send(message);

    System.out.println("Email Message Sent Successfully");

      } catch (MessagingException e) {
         throw new RuntimeException(e);
      }
   }
}

Here is the output:

Send an Email with Attachments in Jakarta Mail

Apart from the previously mentioned steps, here are the differing steps involved in using the Jakarta Mail API for sending email attachments:

  • Create an instance of the MimeMultipart object that will be used for wrapping the MimeBodyPart body parts. A Multipart acts like a container that keeps multiple body parts, and it comes with methods for getting and setting its various subparts. 
  • Then, set the first part of the multipart object by passing the actual message to it. 
  • Next, set the second part of the multipart object by adding the attachment using a DataHandler object.
  • Include the multipart in the message to be sent. 

Here is the code:

package jakartaemail;


import java.util.Properties;

import javax.mail.Message;
import javax.mail.MessagingException;
import javax.mail.PasswordAuthentication;
import javax.mail.Session;
import javax.mail.Transport;
import javax.mail.internet.InternetAddress;
import javax.mail.internet.MimeMessage;
import javax.mail.BodyPart;
import javax.mail.Multipart;
import javax.mail.internet.MimeBodyPart;
import javax.mail.internet.MimeMultipart;
import javax.activation.DataSource;
import javax.activation.DataHandler;
import javax.activation.FileDataSource;

public class JakartaEmail {
   public static void main(String[] args) {
      //provide recipient's email ID
      String to = "jakartato@example.com";

      //provide sender's email ID
      String from = "jakartafrom@example.com";
      //provide Mailtrap's username
      final String username = "a094ccae2cfdb3";
      //provide Mailtrap's password
      final String password = "82a851fcf4aa33";

      //provide Mailtrap's host address 
      String host = "smtp.mailtrap.io";
      //configure Mailtrap's SMTP server details 
      Properties props = new Properties();
      props.put("mail.smtp.auth", "true");
      props.put("mail.smtp.starttls.enable", "true");  
      props.put("mail.smtp.host", host);
      props.put("mail.smtp.port", "587");

      //create the Session object
      Session session = Session.getInstance(props,
         new javax.mail.Authenticator() {
            protected PasswordAuthentication getPasswordAuthentication() {
               return new PasswordAuthentication(username, password);
    }
         });

      try {
    //create a MimeMessage object
    Message message = new MimeMessage(session);
 
    //set From email field 
    message.setFrom(new InternetAddress(from));
 
    //set To email field
    message.setRecipients(Message.RecipientType.TO,
               InternetAddress.parse(to));
 
    //set email subject field
    message.setSubject("Here comes an attachment!");
 
   //create the message body part
    BodyPart messageBodyPart = new MimeBodyPart();

    //set the actual message
    messageBodyPart.setText("Please find the attachment sent using Jakarta Mail");

    //create an instance of multipart object
    Multipart multipart = new MimeMultipart();

    //set the first text message part
    multipart.addBodyPart(messageBodyPart);

    //set the second part, which is the attachment
    messageBodyPart = new MimeBodyPart();
    String filename = "C:\\Users\\OPIDI\\Desktop\\File 1\\gantt2.png";
    DataSource source = new FileDataSource(filename);
    messageBodyPart.setDataHandler(new DataHandler(source));
    messageBodyPart.setFileName(filename);
    multipart.addBodyPart(messageBodyPart);

    //send the entire message parts
    message.setContent(multipart);
        
    //send the email message
    Transport.send(message);

    System.out.println("Email Message Sent Successfully");

      } catch (MessagingException e) {
         throw new RuntimeException(e);
      }
   }
}

Here is the output:

Wrapping up

That’s how you can use the Jakarta Mail API to send email messages in Java. We hope that this article will help you to get started with the API and add powerful emailing capabilities to your Java applications. 

Of course, we’ve just scratched the surface about what is possible with the Jakarta Mail Project. If you want to explore more usage samples, you can always check its expansive documentation.

Importantly, when using Jakarta Mail, don’t forget to always test your emails in your development environment before broadcasting them to users. 

Enjoy using Jakarta Mail!