or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core-mail-operations.mdevent-handling-system.mdindex.mdinternet-mail-mime.mdmessage-search-filtering.mdstore-folder-management.mdutility-classes-streams.md
tile.json

tessl/maven-jakarta-mail--jakarta-mail-api

Jakarta Mail defines a platform-independent and protocol-independent framework to build mail and messaging applications.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/jakarta.mail/jakarta.mail-api@2.1.x

To install, run

npx @tessl/cli install tessl/maven-jakarta-mail--jakarta-mail-api@2.1.0

index.mddocs/

Jakarta Mail API

Jakarta Mail defines a platform-independent and protocol-independent framework to build mail and messaging applications. It provides comprehensive APIs for creating, sending, receiving, and processing email messages with full MIME support, event handling, and search capabilities.

Package Information

  • Package Name: jakarta.mail-api
  • Package Type: Maven
  • Group ID: jakarta.mail
  • Artifact ID: jakarta.mail-api
  • Language: Java
  • Installation: Add to Maven dependencies:
<dependency>
  <groupId>jakarta.mail</groupId>
  <artifactId>jakarta.mail-api</artifactId>
  <version>2.1.3</version>
</dependency>

Or to Gradle dependencies:

implementation 'jakarta.mail:jakarta.mail-api:2.1.3'

Core Imports

import jakarta.mail.*;
import jakarta.mail.internet.*;
import jakarta.mail.search.*;
import jakarta.mail.util.*;
import jakarta.mail.event.*;

// Key classes
import jakarta.mail.Session;
import jakarta.mail.Store;
import jakarta.mail.Transport;
import jakarta.mail.Folder;
import jakarta.mail.Message;
import jakarta.mail.internet.MimeMessage;
import jakarta.mail.internet.InternetAddress;

Basic Usage

import jakarta.mail.*;
import jakarta.mail.internet.*;
import java.util.Properties;

// Create session
Properties props = new Properties();
props.put("mail.smtp.host", "smtp.example.com");
Session session = Session.getInstance(props);

// Create and send message
MimeMessage message = new MimeMessage(session);
message.setFrom(new InternetAddress("sender@example.com"));
message.setRecipients(Message.RecipientType.TO, 
    InternetAddress.parse("recipient@example.com"));
message.setSubject("Hello Jakarta Mail");
message.setText("This is a test message");

Transport.send(message);

// Read messages
Store store = session.getStore("imaps");
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("Subject: " + msg.getSubject());
}
inbox.close(false);
store.close();

Architecture

Jakarta Mail API follows a layered architecture:

  • Session Layer: Configuration and protocol provider management
  • Store/Transport Layer: Message storage and transmission abstractions
  • Message Layer: Email message modeling and manipulation
  • Protocol Layer: Internet-specific implementations (MIME, SMTP, IMAP, POP3)
  • Event Layer: Asynchronous notification system
  • Search Layer: Message querying and filtering
  • Utility Layer: Helper classes for streams and data sources

Capabilities

Core Mail Operations

Essential mail session management, message handling, and transport operations.

// Session management
public final class Session {
    public static Session getInstance(Properties props);
    public static Session getInstance(Properties props, Authenticator authenticator);
    public static Session getDefaultInstance(Properties props);
    public static Session getDefaultInstance(Properties props, Authenticator authenticator);
    
    public Store getStore() throws NoSuchProviderException;
    public Store getStore(String protocol) throws NoSuchProviderException;
    public Store getStore(URLName url) throws NoSuchProviderException;
    public Store getStore(Provider provider) throws NoSuchProviderException;
    
    public Transport getTransport() throws NoSuchProviderException;
    public Transport getTransport(String protocol) throws NoSuchProviderException;
    public Transport getTransport(URLName url) throws NoSuchProviderException;
    public Transport getTransport(Address address) throws NoSuchProviderException;
    public Transport getTransport(Provider provider) throws NoSuchProviderException;
    
    public Folder getFolder(URLName url) throws MessagingException;
    
    // Provider management
    public Provider[] getProviders();
    public Provider getProvider(String protocol) throws NoSuchProviderException;
    public void setProvider(Provider provider) throws NoSuchProviderException;
    public void addProvider(Provider provider);
    
    // Authentication management
    public void setPasswordAuthentication(URLName url, PasswordAuthentication pw);
    public PasswordAuthentication getPasswordAuthentication(URLName url);
    public PasswordAuthentication requestPasswordAuthentication(InetAddress addr, int port, String protocol, String prompt, String defaultUserName);
    
    // Configuration access
    public Properties getProperties();
    public String getProperty(String name);
    
    // Debug support
    public void setDebug(boolean debug);
    public boolean getDebug();
    public PrintStream getDebugOut();
    public void setDebugOut(PrintStream out);
}

// Message operations  
public abstract class Message implements Part {
    // Session and identification
    public Session getSession();
    public int getMessageNumber();
    public Folder getFolder();
    public boolean isExpunged();
    
    // Address management
    public abstract Address[] getFrom() throws MessagingException;
    public abstract void setFrom() throws MessagingException;
    public abstract void setFrom(Address address) throws MessagingException;
    public abstract void addFrom(Address[] addresses) throws MessagingException;
    
    public abstract Address[] getRecipients(RecipientType type) throws MessagingException;
    public Address[] getAllRecipients() throws MessagingException;
    public abstract void setRecipients(RecipientType type, Address[] addresses) throws MessagingException;
    public void setRecipient(RecipientType type, Address address) throws MessagingException;
    public abstract void addRecipients(RecipientType type, Address[] addresses) throws MessagingException;
    public abstract void addRecipients(RecipientType type, String addresses) throws MessagingException;
    public void addRecipient(RecipientType type, Address address) throws MessagingException;
    
    public Address[] getReplyTo() throws MessagingException;
    public void setReplyTo(Address[] addresses) throws MessagingException;
    
    // Subject and dates
    public abstract String getSubject() throws MessagingException;
    public abstract void setSubject(String subject) throws MessagingException;
    public abstract Date getSentDate() throws MessagingException;
    public abstract void setSentDate(Date date) throws MessagingException;
    public abstract Date getReceivedDate() throws MessagingException;
    
    // Message flags
    public abstract Flags getFlags() throws MessagingException;
    public boolean isSet(Flags.Flag flag) throws MessagingException;
    public abstract void setFlags(Flags flag, boolean set) throws MessagingException;
    public void setFlag(Flags.Flag flag, boolean set) throws MessagingException;
    
    // Message operations
    public abstract Message reply(boolean replyToAll) throws MessagingException;
    public abstract void saveChanges() throws MessagingException;
    public boolean match(SearchTerm term) throws MessagingException;
}

// Transport operations
public abstract class Transport extends Service {
    // Constructor
    public Transport(Session session, URLName urlname);
    
    // Static convenience methods
    public static void send(Message msg) throws MessagingException;
    public static void send(Message msg, Address[] addresses) throws MessagingException;
    public static void send(Message msg, String user, String password) throws MessagingException;
    public static void send(Message msg, Address[] addresses, String user, String password) throws MessagingException;
    
    // Instance methods
    public abstract void sendMessage(Message msg, Address[] addresses) throws MessagingException;
    
    // Event handling
    public void addTransportListener(TransportListener l);
    public void removeTransportListener(TransportListener l);
}

Core Mail Operations

Store and Folder Management

Message storage, folder operations, and mailbox management capabilities.

// Store operations
public abstract class Store extends Service {
    public abstract Folder getDefaultFolder() throws MessagingException;
    public abstract Folder getFolder(String name) throws MessagingException;
    public abstract Folder getFolder(URLName url) throws MessagingException;
}

// Folder operations
public abstract class Folder implements AutoCloseable {
    public abstract String getName();
    public abstract String getFullName();
    public abstract boolean exists() throws MessagingException;
    public abstract void open(int mode) throws MessagingException;
    public abstract void close(boolean expunge) throws MessagingException;
    public abstract Message getMessage(int msgnum) throws MessagingException;
    public abstract Message[] getMessages() throws MessagingException;
    public abstract Message[] expunge() throws MessagingException;
}

Store and Folder Management

Internet Mail (MIME) Support

MIME message creation, multipart handling, and internet address management.

// MIME message implementation
public class MimeMessage extends Message implements MimePart {
    public MimeMessage(Session session);
    public MimeMessage(Session session, InputStream is) throws MessagingException;
    public void setText(String text) throws MessagingException;
    public void setText(String text, String charset) throws MessagingException;
    public void setContent(Object o, String type) throws MessagingException;
    public void saveChanges() throws MessagingException;
}

// Internet addresses
public class InternetAddress extends Address implements Cloneable {
    public InternetAddress(String address) throws AddressException;
    public InternetAddress(String address, String personal) throws AddressException;
    public static InternetAddress[] parse(String addresslist) throws AddressException;
    public String getAddress();
    public String getPersonal();
}

// Multipart content
public class MimeMultipart extends Multipart {
    public MimeMultipart();
    public MimeMultipart(String subtype);
    public void addBodyPart(BodyPart part) throws MessagingException;
}

Internet Mail (MIME) Support

Message Search and Filtering

Comprehensive message search capabilities with various criteria and logical operators.

// Search base class
public abstract class SearchTerm implements Serializable {
    public abstract boolean match(Message msg);
}

// String-based searches
public final class SubjectTerm extends StringTerm {
    public SubjectTerm(String pattern);
}

public final class FromStringTerm extends AddressStringTerm {
    public FromStringTerm(String pattern);
}

// Date-based searches  
public final class ReceivedDateTerm extends DateTerm {
    public ReceivedDateTerm(int comparison, Date date);
}

// Logical operators
public final class AndTerm extends SearchTerm {
    public AndTerm(SearchTerm t1, SearchTerm t2);
}

public final class OrTerm extends SearchTerm {
    public OrTerm(SearchTerm t1, SearchTerm t2);
}

Message Search and Filtering

Event Handling System

Comprehensive event system for monitoring mail operations and state changes.

// Event base class
public abstract class MailEvent extends EventObject {
    public Object getSource();
}

// Connection events
public final class ConnectionEvent extends MailEvent {
    public static final int OPENED = 1;
    public static final int DISCONNECTED = 2; 
    public static final int CLOSED = 3;
    public int getType();
}

// Message events
public final class MessageCountEvent extends MailEvent {
    public static final int ADDED = 1;
    public static final int REMOVED = 2;
    public int getType();
    public Message[] getMessages();
}

// Listeners
public interface ConnectionListener extends EventListener {
    public void opened(ConnectionEvent e);
    public void disconnected(ConnectionEvent e);
    public void closed(ConnectionEvent e);
}

Event Handling System

Utility Classes and Streams

Helper classes for data sources, shared streams, and mail-specific utilities.

// Data sources
public class ByteArrayDataSource implements DataSource {
    public ByteArrayDataSource(byte[] data, String type);
    public ByteArrayDataSource(InputStream is, String type) throws IOException;
    public InputStream getInputStream() throws IOException;
    public OutputStream getOutputStream() throws IOException;
}

// Shared input streams
public class SharedFileInputStream extends BufferedInputStream implements SharedInputStream {
    public SharedFileInputStream(File file) throws IOException;
    public InputStream newStream(long start, long end);
    public long getPosition();
}

// MIME utilities
public class MimeUtility {
    public static String encodeText(String text) throws UnsupportedEncodingException;
    public static String decodeText(String etext) throws UnsupportedEncodingException;
    public static InputStream encode(InputStream is, String encoding) throws MessagingException;
    public static InputStream decode(InputStream is, String encoding) throws MessagingException;
}

Utility Classes and Streams

Core Types

Address Types

// Base address class
public abstract class Address implements Serializable {
    public abstract String getType();
    public abstract String toString();
    public abstract boolean equals(Object address);
}

// Internet address implementation
public class InternetAddress extends Address implements Cloneable {
    public InternetAddress(String address) throws AddressException;
    public InternetAddress(String address, String personal) throws AddressException;
    public String getAddress();
    public void setAddress(String address) throws AddressException;
    public String getPersonal();
    public void setPersonal(String name) throws UnsupportedEncodingException;
}

// News address implementation  
public class NewsAddress extends Address {
    public NewsAddress(String newsgroup);
    public String getNewsgroup();
}

Message Types

// Recipient types
public static final class Message.RecipientType implements Serializable {
    public static final RecipientType TO;
    public static final RecipientType CC;
    public static final RecipientType BCC;
}

// Message flags
public class Flags implements Cloneable, Serializable {
    public static final class Flag {
        public static final Flag ANSWERED;
        public static final Flag DELETED;
        public static final Flag DRAFT;
        public static final Flag FLAGGED;
        public static final Flag RECENT;
        public static final Flag SEEN;
        public static final Flag USER;
    }
    
    public void add(Flag flag);
    public void add(String flag);
    public boolean contains(Flag flag);
    public boolean contains(String flag);
    public Flag[] getSystemFlags();
    public String[] getUserFlags();
}

Authentication Types

// Authentication callback
public abstract class Authenticator {
    protected PasswordAuthentication getPasswordAuthentication();
    protected String getDefaultUserName();
    protected String getRequestingPrompt();
    protected InetAddress getRequestingSite();
    protected String getRequestingProtocol();
}

// Username/password pair
public final class PasswordAuthentication {
    public PasswordAuthentication(String userName, String password);
    public String getUserName();
    public String getPassword();
}

Provider Types

// Protocol provider information
public class Provider {
    public static final class Type {
        public static final Type STORE;
        public static final Type TRANSPORT;
    }
    
    public Type getType();
    public String getProtocol();
    public String getClassName();
    public String getVendor();
    public String getVersion();
}

// URL name for mail connections
public class URLName {
    public URLName(String protocol, String host, int port, String file, String username, String password);
    public String getProtocol();
    public String getHost();
    public int getPort();
    public String getFile();
    public String getUsername();
    public String getPassword();
}

Exception Types

// Base mail exception
public class MessagingException extends Exception {
    public MessagingException();
    public MessagingException(String message);
    public MessagingException(String message, Exception e);
    public Exception getNextException();
    public void setNextException(Exception ex);
}

// Authentication failure
public class AuthenticationFailedException extends MessagingException {
    public AuthenticationFailedException();
    public AuthenticationFailedException(String message);
}

// Send operation failure
public class SendFailedException extends MessagingException {
    public SendFailedException();
    public SendFailedException(String message);
    public Address[] getValidSentAddresses();
    public Address[] getValidUnsentAddresses();
    public Address[] getInvalidAddresses();
}

Module Information

module jakarta.mail {
    requires java.logging;
    requires transitive jakarta.activation;
    requires static java.desktop;
    
    exports jakarta.mail;
    exports jakarta.mail.event;
    exports jakarta.mail.internet;
    exports jakarta.mail.search;
    exports jakarta.mail.util;
    
    uses jakarta.mail.Provider;
    uses jakarta.mail.util.StreamProvider;
}