0
# Jakarta Mail API
1

2
Jakarta Mail API provides a platform-independent and protocol-independent framework to build mail and messaging applications. It offers comprehensive support for SMTP, IMAP, POP3 protocols with MIME message handling, folder operations, search capabilities, and event-driven programming.
3

4
## Package Information
5

6
- **Package Name**: jakarta.mail-api
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
      <groupId>com.sun.mail</groupId>
13
      <artifactId>jakarta.mail</artifactId>
14
      <version>1.6.7</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
import javax.mail.*;
22
import javax.mail.internet.*;
23
import javax.mail.search.*;
24
import javax.mail.event.*;
25
import java.util.Properties;
26
import javax.activation.DataHandler;
27
```
28

29
## Basic Usage
30

31
```java
32
// Create session
33
Properties props = new Properties();
34
props.put("mail.smtp.host", "smtp.example.com");
35
props.put("mail.smtp.port", "587");
36
props.put("mail.smtp.auth", "true");
37
props.put("mail.smtp.starttls.enable", "true");
38

39
Session session = Session.getInstance(props, new Authenticator() {
40
    protected PasswordAuthentication getPasswordAuthentication() {
41
        return new PasswordAuthentication("username", "password");
42
    }
43
});
44

45
// Create and send message
46
Message message = new MimeMessage(session);
47
message.setFrom(new InternetAddress("sender@example.com"));
48
message.setRecipients(Message.RecipientType.TO, 
49
                      InternetAddress.parse("recipient@example.com"));
50
message.setSubject("Hello World");
51
message.setText("This is a test message.");
52

53
Transport.send(message);
54

55
// Read messages
56
Store store = session.getStore("imap");
57
store.connect("imap.example.com", "username", "password");
58
Folder inbox = store.getFolder("INBOX");
59
inbox.open(Folder.READ_ONLY);
60
Message[] messages = inbox.getMessages();
61
```
62

63
## Architecture
64

65
The Jakarta Mail API follows a provider-based architecture with these key components:
66

67
- **Session**: Entry point that manages configuration and provider access
68
- **Store**: Represents message storage systems (IMAP, POP3)  
69
- **Transport**: Handles message delivery (SMTP)
70
- **Folder**: Container for messages with hierarchical organization
71
- **Message**: Represents email messages with MIME support
72
- **Address**: Handles email addressing (InternetAddress, NewsAddress)
73

74
## Capabilities
75

76
### Core Messaging
77

78
Session management, message creation, transport operations, and store connectivity.
79

80
```java { .api }
81
class Session {
82
    // Static factory methods
83
    public static Session getInstance(Properties props);
84
    public static Session getInstance(Properties props, Authenticator authenticator);
85
    public static synchronized Session getDefaultInstance(Properties props);
86
    public static synchronized Session getDefaultInstance(Properties props, Authenticator authenticator);
87
    
88
    // Store and Transport access
89
    public Store getStore() throws NoSuchProviderException;
90
    public Store getStore(String protocol) throws NoSuchProviderException;
91
    public Store getStore(URLName url) throws NoSuchProviderException;
92
    public Store getStore(Provider provider) throws NoSuchProviderException;
93
    public Transport getTransport() throws NoSuchProviderException;
94
    public Transport getTransport(String protocol) throws NoSuchProviderException;
95
    public Transport getTransport(URLName url) throws NoSuchProviderException;
96
    public Transport getTransport(Provider provider) throws NoSuchProviderException;
97
    public Transport getTransport(Address address) throws NoSuchProviderException;
98
    
99
    // Folder access
100
    public Folder getFolder(URLName url) throws MessagingException;
101
    
102
    // Properties and configuration
103
    public Properties getProperties();
104
    public String getProperty(String name);
105
    
106
    // Provider management
107
    public synchronized Provider[] getProviders();
108
    public synchronized Provider getProvider(String protocol) throws NoSuchProviderException;
109
    public synchronized void setProvider(Provider provider) throws NoSuchProviderException;
110
    public synchronized void addProvider(Provider provider);
111
    
112
    // Authentication
113
    public void setPasswordAuthentication(URLName url, PasswordAuthentication pw);
114
    public PasswordAuthentication getPasswordAuthentication(URLName url);
115
    public PasswordAuthentication requestPasswordAuthentication(InetAddress addr, int port, String protocol, String prompt, String defaultUserName);
116
    
117
    // Debug support
118
    public synchronized void setDebug(boolean debug);
119
    public synchronized boolean getDebug();
120
    public synchronized void setDebugOut(PrintStream out);
121
    public synchronized PrintStream getDebugOut();
122
    
123
    // Protocol configuration
124
    public synchronized void setProtocolForAddress(String addresstype, String protocol);
125
}
126

127
abstract class Message implements Part {
128
    // Address management
129
    public abstract Address[] getFrom() throws MessagingException;
130
    public abstract void setFrom() throws MessagingException;
131
    public abstract void setFrom(Address address) throws MessagingException;
132
    public abstract void addFrom(Address[] addresses) throws MessagingException;
133
    public abstract Address[] getRecipients(RecipientType type) throws MessagingException;
134
    public abstract void setRecipients(RecipientType type, Address[] addresses) throws MessagingException;
135
    public abstract void addRecipients(RecipientType type, Address[] addresses) throws MessagingException;
136
    
137
    // Subject and dates
138
    public abstract String getSubject() throws MessagingException;
139
    public abstract void setSubject(String subject) throws MessagingException;
140
    public abstract Date getSentDate() throws MessagingException;
141
    public abstract void setSentDate(Date date) throws MessagingException;
142
    public abstract Date getReceivedDate() throws MessagingException;
143
    
144
    // Flag management
145
    public abstract Flags getFlags() throws MessagingException;
146
    public abstract void setFlags(Flags flag, boolean set) throws MessagingException;
147
    
148
    // Operations
149
    public abstract Message reply(boolean replyToAll) throws MessagingException;
150
    public abstract void saveChanges() throws MessagingException;
151
}
152

153
abstract class Transport extends Service {
154
    // Static send methods
155
    public static void send(Message msg) throws MessagingException;
156
    public static void send(Message msg, Address[] addresses) throws MessagingException;
157
    public static void send(Message msg, String user, String password) throws MessagingException;
158
    public static void send(Message msg, Address[] addresses, String user, String password) throws MessagingException;
159
    
160
    // Instance methods
161
    public abstract void sendMessage(Message msg, Address[] addresses) throws MessagingException;
162
}
163
```
164

165
[Core Messaging](./core-messaging.md)
166

167
### Internet Messaging
168

169
MIME message handling, multipart content, address parsing, and encoding utilities.
170

171
```java { .api }
172
class MimeMessage extends Message implements MimePart {
173
    public MimeMessage(Session session);
174
    public MimeMessage(Session session, InputStream is) throws MessagingException;
175
    public MimeMessage(MimeMessage source) throws MessagingException;
176
    
177
    public void setText(String text) throws MessagingException;
178
    public void setContent(Object o, String type) throws MessagingException;
179
    public void setContent(Multipart mp) throws MessagingException;
180
    public Object getContent() throws IOException, MessagingException;
181
    public String getContentType() throws MessagingException;
182
    
183
    public void setHeader(String name, String value) throws MessagingException;
184
    public String[] getHeader(String name) throws MessagingException;
185
    public void addHeader(String name, String value) throws MessagingException;
186
    public void removeHeader(String name) throws MessagingException;
187
    
188
    public String getMessageID() throws MessagingException;
189
    public void updateHeaders() throws MessagingException;
190
}
191

192
class InternetAddress extends Address {
193
    public InternetAddress();
194
    public InternetAddress(String address) throws AddressException;
195
    public InternetAddress(String address, String personal) throws AddressException;
196
    public InternetAddress(String address, String personal, String charset) throws UnsupportedEncodingException;
197
    
198
    public String getAddress();
199
    public void setAddress(String address);
200
    public String getPersonal();
201
    public void setPersonal(String name) throws UnsupportedEncodingException;
202
    
203
    public static InternetAddress[] parse(String addresslist) throws AddressException;
204
    public static InternetAddress[] parse(String addresslist, boolean strict) throws AddressException;
205
    public static InternetAddress[] parseHeader(String addresslist, boolean strict) throws AddressException;
206
    
207
    public void validate() throws AddressException;
208
    public boolean isGroup();
209
    public InternetAddress[] getGroup(boolean strict) throws AddressException;
210
}
211

212
class MimeMultipart extends Multipart {
213
    public MimeMultipart();
214
    public MimeMultipart(String subtype) throws MessagingException;
215
    public MimeMultipart(DataSource ds) throws MessagingException;
216
    
217
    public void addBodyPart(BodyPart part) throws MessagingException;
218
    public void addBodyPart(BodyPart part, int index) throws MessagingException;
219
    public BodyPart getBodyPart(int index) throws MessagingException;
220
    public boolean removeBodyPart(BodyPart part) throws MessagingException;
221
    public int getCount() throws MessagingException;
222
    
223
    public String getPreamble() throws MessagingException;
224
    public void setPreamble(String preamble) throws MessagingException;
225
}
226
```
227

228
[Internet Messaging](./internet-messaging.md)
229

230
### Folder Operations
231

232
Folder management, message storage, flag operations, and hierarchical navigation.
233

234
```java { .api }
235
abstract class Folder implements AutoCloseable {
236
    abstract void open(int mode) throws MessagingException;
237
    abstract Message[] getMessages() throws MessagingException;
238
    abstract void appendMessages(Message[] msgs) throws MessagingException;
239
    abstract Message[] expunge() throws MessagingException;
240
    abstract Folder[] list(String pattern) throws MessagingException;
241
}
242

243
abstract class Store extends Service {
244
    abstract Folder getDefaultFolder() throws MessagingException;
245
    abstract Folder getFolder(String name) throws MessagingException;
246
}
247
```
248

249
[Folder Operations](./folder-operations.md)
250

251
### Search Capabilities
252

253
Message searching with complex criteria, logical operators, and content filtering.
254

255
```java { .api }
256
abstract class SearchTerm implements Serializable {
257
    abstract boolean match(Message msg);
258
}
259

260
class AndTerm extends SearchTerm {
261
    AndTerm(SearchTerm t1, SearchTerm t2);
262
    AndTerm(SearchTerm[] terms);
263
}
264

265
class SubjectTerm extends StringTerm {
266
    SubjectTerm(String pattern);
267
}
268

269
class FromTerm extends AddressTerm {
270
    FromTerm(Address address);
271
}
272
```
273

274
[Search Capabilities](./search-capabilities.md)
275

276
### Event Handling
277

278
Mail event listeners, connection monitoring, and message change notifications.
279

280
```java { .api }
281
interface MessageCountListener extends EventListener {
282
    void messagesAdded(MessageCountEvent e);
283
    void messagesRemoved(MessageCountEvent e);
284
}
285

286
interface ConnectionListener extends EventListener {
287
    void opened(ConnectionEvent e);
288
    void closed(ConnectionEvent e);
289
    void disconnected(ConnectionEvent e);
290
}
291

292
abstract class MessageCountAdapter implements MessageCountListener {
293
    // Empty implementations for optional override
294
}
295
```
296

297
[Event Handling](./event-handling.md)
298

299
## Core Types
300

301
```java { .api }
302
class Properties extends Hashtable<Object,Object> {
303
    String getProperty(String key);
304
    Object setProperty(String key, String value);
305
}
306

307
abstract class Authenticator {
308
    protected PasswordAuthentication getPasswordAuthentication();
309
}
310

311
class PasswordAuthentication {
312
    PasswordAuthentication(String userName, String password);
313
    String getUserName();
314
    String getPassword();
315
}
316

317
class MessagingException extends Exception {
318
    MessagingException();
319
    MessagingException(String s);
320
    MessagingException(String s, Exception e);
321
}
322

323
class Flags implements Cloneable, Serializable {
324
    Flags();
325
    Flags(Flag flag);
326
    void add(Flag flag);
327
    boolean contains(Flag flag);
328
    
329
    static class Flag {
330
        static final Flag ANSWERED;
331
        static final Flag DELETED;
332
        static final Flag DRAFT;
333
        static final Flag FLAGGED;
334
        static final Flag RECENT;
335
        static final Flag SEEN;
336
    }
337
}
338
```