0
# Jakarta Mail API
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: jakarta.mail-api
7
- **Package Type**: Maven
8
- **Group ID**: jakarta.mail
9
- **Artifact ID**: jakarta.mail-api
10
- **Language**: Java
11
- **Installation**: Add to Maven dependencies:
12

13
```xml
14
<dependency>
15
  <groupId>jakarta.mail</groupId>
16
  <artifactId>jakarta.mail-api</artifactId>
17
  <version>2.1.3</version>
18
</dependency>
19
```
20

21
Or to Gradle dependencies:
22

23
```gradle
24
implementation 'jakarta.mail:jakarta.mail-api:2.1.3'
25
```
26

27
## Core Imports
28

29
```java
30
import jakarta.mail.*;
31
import jakarta.mail.internet.*;
32
import jakarta.mail.search.*;
33
import jakarta.mail.util.*;
34
import jakarta.mail.event.*;
35

36
// Key classes
37
import jakarta.mail.Session;
38
import jakarta.mail.Store;
39
import jakarta.mail.Transport;
40
import jakarta.mail.Folder;
41
import jakarta.mail.Message;
42
import jakarta.mail.internet.MimeMessage;
43
import jakarta.mail.internet.InternetAddress;
44
```
45

46
## Basic Usage
47

48
```java
49
import jakarta.mail.*;
50
import jakarta.mail.internet.*;
51
import java.util.Properties;
52

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

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

66
Transport.send(message);
67

68
// Read messages
69
Store store = session.getStore("imaps");
70
store.connect("imap.example.com", "username", "password");
71
Folder inbox = store.getFolder("INBOX");
72
inbox.open(Folder.READ_ONLY);
73
Message[] messages = inbox.getMessages();
74
for (Message msg : messages) {
75
    System.out.println("Subject: " + msg.getSubject());
76
}
77
inbox.close(false);
78
store.close();
79
```
80

81
## Architecture
82

83
Jakarta Mail API follows a layered architecture:
84

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

93
## Capabilities
94

95
### Core Mail Operations
96

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

99
```java { .api }
100
// Session management
101
public final class Session {
102
    public static Session getInstance(Properties props);
103
    public static Session getInstance(Properties props, Authenticator authenticator);
104
    public static Session getDefaultInstance(Properties props);
105
    public static Session getDefaultInstance(Properties props, Authenticator authenticator);
106
    
107
    public Store getStore() throws NoSuchProviderException;
108
    public Store getStore(String protocol) throws NoSuchProviderException;
109
    public Store getStore(URLName url) throws NoSuchProviderException;
110
    public Store getStore(Provider provider) throws NoSuchProviderException;
111
    
112
    public Transport getTransport() throws NoSuchProviderException;
113
    public Transport getTransport(String protocol) throws NoSuchProviderException;
114
    public Transport getTransport(URLName url) throws NoSuchProviderException;
115
    public Transport getTransport(Address address) throws NoSuchProviderException;
116
    public Transport getTransport(Provider provider) throws NoSuchProviderException;
117
    
118
    public Folder getFolder(URLName url) throws MessagingException;
119
    
120
    // Provider management
121
    public Provider[] getProviders();
122
    public Provider getProvider(String protocol) throws NoSuchProviderException;
123
    public void setProvider(Provider provider) throws NoSuchProviderException;
124
    public void addProvider(Provider provider);
125
    
126
    // Authentication management
127
    public void setPasswordAuthentication(URLName url, PasswordAuthentication pw);
128
    public PasswordAuthentication getPasswordAuthentication(URLName url);
129
    public PasswordAuthentication requestPasswordAuthentication(InetAddress addr, int port, String protocol, String prompt, String defaultUserName);
130
    
131
    // Configuration access
132
    public Properties getProperties();
133
    public String getProperty(String name);
134
    
135
    // Debug support
136
    public void setDebug(boolean debug);
137
    public boolean getDebug();
138
    public PrintStream getDebugOut();
139
    public void setDebugOut(PrintStream out);
140
}
141

142
// Message operations  
143
public abstract class Message implements Part {
144
    // Session and identification
145
    public Session getSession();
146
    public int getMessageNumber();
147
    public Folder getFolder();
148
    public boolean isExpunged();
149
    
150
    // Address management
151
    public abstract Address[] getFrom() throws MessagingException;
152
    public abstract void setFrom() throws MessagingException;
153
    public abstract void setFrom(Address address) throws MessagingException;
154
    public abstract void addFrom(Address[] addresses) throws MessagingException;
155
    
156
    public abstract Address[] getRecipients(RecipientType type) throws MessagingException;
157
    public Address[] getAllRecipients() throws MessagingException;
158
    public abstract void setRecipients(RecipientType type, Address[] addresses) throws MessagingException;
159
    public void setRecipient(RecipientType type, Address address) throws MessagingException;
160
    public abstract void addRecipients(RecipientType type, Address[] addresses) throws MessagingException;
161
    public abstract void addRecipients(RecipientType type, String addresses) throws MessagingException;
162
    public void addRecipient(RecipientType type, Address address) throws MessagingException;
163
    
164
    public Address[] getReplyTo() throws MessagingException;
165
    public void setReplyTo(Address[] addresses) throws MessagingException;
166
    
167
    // Subject and dates
168
    public abstract String getSubject() throws MessagingException;
169
    public abstract void setSubject(String subject) throws MessagingException;
170
    public abstract Date getSentDate() throws MessagingException;
171
    public abstract void setSentDate(Date date) throws MessagingException;
172
    public abstract Date getReceivedDate() throws MessagingException;
173
    
174
    // Message flags
175
    public abstract Flags getFlags() throws MessagingException;
176
    public boolean isSet(Flags.Flag flag) throws MessagingException;
177
    public abstract void setFlags(Flags flag, boolean set) throws MessagingException;
178
    public void setFlag(Flags.Flag flag, boolean set) throws MessagingException;
179
    
180
    // Message operations
181
    public abstract Message reply(boolean replyToAll) throws MessagingException;
182
    public abstract void saveChanges() throws MessagingException;
183
    public boolean match(SearchTerm term) throws MessagingException;
184
}
185

186
// Transport operations
187
public abstract class Transport extends Service {
188
    // Constructor
189
    public Transport(Session session, URLName urlname);
190
    
191
    // Static convenience methods
192
    public static void send(Message msg) throws MessagingException;
193
    public static void send(Message msg, Address[] addresses) throws MessagingException;
194
    public static void send(Message msg, String user, String password) throws MessagingException;
195
    public static void send(Message msg, Address[] addresses, String user, String password) throws MessagingException;
196
    
197
    // Instance methods
198
    public abstract void sendMessage(Message msg, Address[] addresses) throws MessagingException;
199
    
200
    // Event handling
201
    public void addTransportListener(TransportListener l);
202
    public void removeTransportListener(TransportListener l);
203
}
204
```
205

206
[Core Mail Operations](./core-mail-operations.md)
207

208
### Store and Folder Management
209

210
Message storage, folder operations, and mailbox management capabilities.
211

212
```java { .api }
213
// Store operations
214
public abstract class Store extends Service {
215
    public abstract Folder getDefaultFolder() throws MessagingException;
216
    public abstract Folder getFolder(String name) throws MessagingException;
217
    public abstract Folder getFolder(URLName url) throws MessagingException;
218
}
219

220
// Folder operations
221
public abstract class Folder implements AutoCloseable {
222
    public abstract String getName();
223
    public abstract String getFullName();
224
    public abstract boolean exists() throws MessagingException;
225
    public abstract void open(int mode) throws MessagingException;
226
    public abstract void close(boolean expunge) throws MessagingException;
227
    public abstract Message getMessage(int msgnum) throws MessagingException;
228
    public abstract Message[] getMessages() throws MessagingException;
229
    public abstract Message[] expunge() throws MessagingException;
230
}
231
```
232

233
[Store and Folder Management](./store-folder-management.md)
234

235
### Internet Mail (MIME) Support
236

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

239
```java { .api }
240
// MIME message implementation
241
public class MimeMessage extends Message implements MimePart {
242
    public MimeMessage(Session session);
243
    public MimeMessage(Session session, InputStream is) throws MessagingException;
244
    public void setText(String text) throws MessagingException;
245
    public void setText(String text, String charset) throws MessagingException;
246
    public void setContent(Object o, String type) throws MessagingException;
247
    public void saveChanges() throws MessagingException;
248
}
249

250
// Internet addresses
251
public class InternetAddress extends Address implements Cloneable {
252
    public InternetAddress(String address) throws AddressException;
253
    public InternetAddress(String address, String personal) throws AddressException;
254
    public static InternetAddress[] parse(String addresslist) throws AddressException;
255
    public String getAddress();
256
    public String getPersonal();
257
}
258

259
// Multipart content
260
public class MimeMultipart extends Multipart {
261
    public MimeMultipart();
262
    public MimeMultipart(String subtype);
263
    public void addBodyPart(BodyPart part) throws MessagingException;
264
}
265
```
266

267
[Internet Mail (MIME) Support](./internet-mail-mime.md)
268

269
### Message Search and Filtering
270

271
Comprehensive message search capabilities with various criteria and logical operators.
272

273
```java { .api }
274
// Search base class
275
public abstract class SearchTerm implements Serializable {
276
    public abstract boolean match(Message msg);
277
}
278

279
// String-based searches
280
public final class SubjectTerm extends StringTerm {
281
    public SubjectTerm(String pattern);
282
}
283

284
public final class FromStringTerm extends AddressStringTerm {
285
    public FromStringTerm(String pattern);
286
}
287

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

293
// Logical operators
294
public final class AndTerm extends SearchTerm {
295
    public AndTerm(SearchTerm t1, SearchTerm t2);
296
}
297

298
public final class OrTerm extends SearchTerm {
299
    public OrTerm(SearchTerm t1, SearchTerm t2);
300
}
301
```
302

303
[Message Search and Filtering](./message-search-filtering.md)
304

305
### Event Handling System  
306

307
Comprehensive event system for monitoring mail operations and state changes.
308

309
```java { .api }
310
// Event base class
311
public abstract class MailEvent extends EventObject {
312
    public Object getSource();
313
}
314

315
// Connection events
316
public final class ConnectionEvent extends MailEvent {
317
    public static final int OPENED = 1;
318
    public static final int DISCONNECTED = 2; 
319
    public static final int CLOSED = 3;
320
    public int getType();
321
}
322

323
// Message events
324
public final class MessageCountEvent extends MailEvent {
325
    public static final int ADDED = 1;
326
    public static final int REMOVED = 2;
327
    public int getType();
328
    public Message[] getMessages();
329
}
330

331
// Listeners
332
public interface ConnectionListener extends EventListener {
333
    public void opened(ConnectionEvent e);
334
    public void disconnected(ConnectionEvent e);
335
    public void closed(ConnectionEvent e);
336
}
337
```
338

339
[Event Handling System](./event-handling-system.md)
340

341
### Utility Classes and Streams
342

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

345
```java { .api }
346
// Data sources
347
public class ByteArrayDataSource implements DataSource {
348
    public ByteArrayDataSource(byte[] data, String type);
349
    public ByteArrayDataSource(InputStream is, String type) throws IOException;
350
    public InputStream getInputStream() throws IOException;
351
    public OutputStream getOutputStream() throws IOException;
352
}
353

354
// Shared input streams
355
public class SharedFileInputStream extends BufferedInputStream implements SharedInputStream {
356
    public SharedFileInputStream(File file) throws IOException;
357
    public InputStream newStream(long start, long end);
358
    public long getPosition();
359
}
360

361
// MIME utilities
362
public class MimeUtility {
363
    public static String encodeText(String text) throws UnsupportedEncodingException;
364
    public static String decodeText(String etext) throws UnsupportedEncodingException;
365
    public static InputStream encode(InputStream is, String encoding) throws MessagingException;
366
    public static InputStream decode(InputStream is, String encoding) throws MessagingException;
367
}
368
```
369

370
[Utility Classes and Streams](./utility-classes-streams.md)
371

372
## Core Types
373

374
### Address Types
375

376
```java { .api }
377
// Base address class
378
public abstract class Address implements Serializable {
379
    public abstract String getType();
380
    public abstract String toString();
381
    public abstract boolean equals(Object address);
382
}
383

384
// Internet address implementation
385
public class InternetAddress extends Address implements Cloneable {
386
    public InternetAddress(String address) throws AddressException;
387
    public InternetAddress(String address, String personal) throws AddressException;
388
    public String getAddress();
389
    public void setAddress(String address) throws AddressException;
390
    public String getPersonal();
391
    public void setPersonal(String name) throws UnsupportedEncodingException;
392
}
393

394
// News address implementation  
395
public class NewsAddress extends Address {
396
    public NewsAddress(String newsgroup);
397
    public String getNewsgroup();
398
}
399
```
400

401
### Message Types
402

403
```java { .api }
404
// Recipient types
405
public static final class Message.RecipientType implements Serializable {
406
    public static final RecipientType TO;
407
    public static final RecipientType CC;
408
    public static final RecipientType BCC;
409
}
410

411
// Message flags
412
public class Flags implements Cloneable, Serializable {
413
    public static final class Flag {
414
        public static final Flag ANSWERED;
415
        public static final Flag DELETED;
416
        public static final Flag DRAFT;
417
        public static final Flag FLAGGED;
418
        public static final Flag RECENT;
419
        public static final Flag SEEN;
420
        public static final Flag USER;
421
    }
422
    
423
    public void add(Flag flag);
424
    public void add(String flag);
425
    public boolean contains(Flag flag);
426
    public boolean contains(String flag);
427
    public Flag[] getSystemFlags();
428
    public String[] getUserFlags();
429
}
430
```
431

432
### Authentication Types
433

434
```java { .api }
435
// Authentication callback
436
public abstract class Authenticator {
437
    protected PasswordAuthentication getPasswordAuthentication();
438
    protected String getDefaultUserName();
439
    protected String getRequestingPrompt();
440
    protected InetAddress getRequestingSite();
441
    protected String getRequestingProtocol();
442
}
443

444
// Username/password pair
445
public final class PasswordAuthentication {
446
    public PasswordAuthentication(String userName, String password);
447
    public String getUserName();
448
    public String getPassword();
449
}
450
```
451

452
### Provider Types
453

454
```java { .api }
455
// Protocol provider information
456
public class Provider {
457
    public static final class Type {
458
        public static final Type STORE;
459
        public static final Type TRANSPORT;
460
    }
461
    
462
    public Type getType();
463
    public String getProtocol();
464
    public String getClassName();
465
    public String getVendor();
466
    public String getVersion();
467
}
468

469
// URL name for mail connections
470
public class URLName {
471
    public URLName(String protocol, String host, int port, String file, String username, String password);
472
    public String getProtocol();
473
    public String getHost();
474
    public int getPort();
475
    public String getFile();
476
    public String getUsername();
477
    public String getPassword();
478
}
479
```
480

481
### Exception Types
482

483
```java { .api }
484
// Base mail exception
485
public class MessagingException extends Exception {
486
    public MessagingException();
487
    public MessagingException(String message);
488
    public MessagingException(String message, Exception e);
489
    public Exception getNextException();
490
    public void setNextException(Exception ex);
491
}
492

493
// Authentication failure
494
public class AuthenticationFailedException extends MessagingException {
495
    public AuthenticationFailedException();
496
    public AuthenticationFailedException(String message);
497
}
498

499
// Send operation failure
500
public class SendFailedException extends MessagingException {
501
    public SendFailedException();
502
    public SendFailedException(String message);
503
    public Address[] getValidSentAddresses();
504
    public Address[] getValidUnsentAddresses();
505
    public Address[] getInvalidAddresses();
506
}
507
```
508

509
## Module Information
510

511
```java { .api }
512
module jakarta.mail {
513
    requires java.logging;
514
    requires transitive jakarta.activation;
515
    requires static java.desktop;
516
    
517
    exports jakarta.mail;
518
    exports jakarta.mail.event;
519
    exports jakarta.mail.internet;
520
    exports jakarta.mail.search;
521
    exports jakarta.mail.util;
522
    
523
    uses jakarta.mail.Provider;
524
    uses jakarta.mail.util.StreamProvider;
525
}
526
```