0
# Core Mail Operations
1

2
Core mail operations provide essential session management, message handling, and transport functionality for Jakarta Mail applications.
3

4
## Session Management
5

6
The Session class is the entry point for Jakarta Mail operations, managing configuration properties and protocol providers.
7

8
```java { .api }
9
public final class Session {
10
    // Create new session instances  
11
    public static Session getInstance(Properties props);
12
    public static Session getInstance(Properties props, Authenticator authenticator);
13
    
14
    // Get default shared session (thread-safe)
15
    public static Session getDefaultInstance(Properties props);
16
    public static Session getDefaultInstance(Properties props, Authenticator authenticator);
17
    
18
    // Protocol provider access
19
    public Store getStore() throws NoSuchProviderException;
20
    public Store getStore(String protocol) throws NoSuchProviderException;
21
    public Store getStore(URLName url) throws NoSuchProviderException;
22
    public Store getStore(Provider provider) throws NoSuchProviderException;
23
    
24
    public Transport getTransport() throws NoSuchProviderException;
25
    public Transport getTransport(String protocol) throws NoSuchProviderException;
26
    public Transport getTransport(URLName url) throws NoSuchProviderException;
27
    public Transport getTransport(Address address) throws NoSuchProviderException;
28
    public Transport getTransport(Provider provider) throws NoSuchProviderException;
29
    
30
    public Folder getFolder(URLName url) throws MessagingException;
31
    
32
    // Provider management
33
    public Provider[] getProviders();
34
    public Provider getProvider(String protocol) throws NoSuchProviderException;
35
    public void setProvider(Provider provider) throws NoSuchProviderException;
36
    public void addProvider(Provider provider);
37
    
38
    // Authentication management
39
    public void setPasswordAuthentication(URLName url, PasswordAuthentication pw);
40
    public PasswordAuthentication getPasswordAuthentication(URLName url);
41
    public PasswordAuthentication requestPasswordAuthentication(InetAddress addr, int port, String protocol, String prompt, String defaultUserName);
42
    
43
    // Configuration access
44
    public Properties getProperties();
45
    public String getProperty(String name);
46
    
47
    // Debug support
48
    public void setDebug(boolean debug);
49
    public boolean getDebug();
50
    public PrintStream getDebugOut();
51
    public void setDebugOut(PrintStream out);
52
}
53
```
54

55
### Session Usage Example
56

57
```java
58
import jakarta.mail.*;
59
import java.util.Properties;
60

61
// Basic session creation
62
Properties props = new Properties();
63
props.put("mail.smtp.host", "smtp.gmail.com");
64
props.put("mail.smtp.port", "587");
65
props.put("mail.smtp.auth", "true");
66
props.put("mail.smtp.starttls.enable", "true");
67

68
Session session = Session.getInstance(props, new Authenticator() {
69
    protected PasswordAuthentication getPasswordAuthentication() {
70
        return new PasswordAuthentication("username@gmail.com", "password");
71
    }
72
});
73

74
// Enable debug output
75
session.setDebug(true);
76
```
77

78
## Message Operations
79

80
The Message abstract class provides the core interface for email message manipulation.
81

82
```java { .api }
83
public abstract class Message implements Part {
84
    // Message identification
85
    public Session getSession();
86
    public int getMessageNumber();
87
    public Folder getFolder();
88
    public boolean isExpunged();
89
    
90
    // Address management
91
    public abstract Address[] getFrom() throws MessagingException;
92
    public abstract void setFrom() throws MessagingException;
93
    public abstract void setFrom(Address address) throws MessagingException;
94
    public abstract void addFrom(Address[] addresses) throws MessagingException;
95
    
96
    public abstract Address[] getRecipients(RecipientType type) throws MessagingException;
97
    public Address[] getAllRecipients() throws MessagingException;
98
    public abstract void setRecipients(RecipientType type, Address[] addresses) throws MessagingException;
99
    public void setRecipient(RecipientType type, Address address) throws MessagingException;
100
    public abstract void addRecipients(RecipientType type, Address[] addresses) throws MessagingException;
101
    public abstract void addRecipients(RecipientType type, String addresses) throws MessagingException;
102
    public void addRecipient(RecipientType type, Address address) throws MessagingException;
103
    
104
    public Address[] getReplyTo() throws MessagingException;
105
    public void setReplyTo(Address[] addresses) throws MessagingException;
106
    
107
    // Subject and dates
108
    public abstract String getSubject() throws MessagingException;
109
    public abstract void setSubject(String subject) throws MessagingException;
110
    public abstract Date getSentDate() throws MessagingException;
111
    public abstract void setSentDate(Date date) throws MessagingException;
112
    public abstract Date getReceivedDate() throws MessagingException;
113
    
114
    // Message flags
115
    public abstract Flags getFlags() throws MessagingException;
116
    public boolean isSet(Flags.Flag flag) throws MessagingException;
117
    public abstract void setFlags(Flags flag, boolean set) throws MessagingException;
118
    public void setFlag(Flags.Flag flag, boolean set) throws MessagingException;
119
    
120
    // Message operations
121
    public abstract Message reply(boolean replyToAll) throws MessagingException;
122
    public abstract void saveChanges() throws MessagingException;
123
    public boolean match(SearchTerm term) throws MessagingException;
124
    
125
    // Content operations (inherited from Part)
126
    public Object getContent() throws IOException, MessagingException;
127
    public String getContentType() throws MessagingException;
128
    public int getSize() throws MessagingException;
129
    public InputStream getInputStream() throws IOException, MessagingException;
130
}
131
```
132

133
### Recipient Types
134

135
```java { .api }
136
public static final class Message.RecipientType implements Serializable {
137
    public static final RecipientType TO;
138
    public static final RecipientType CC;
139
    public static final RecipientType BCC;
140
    
141
    public String toString();
142
}
143
```
144

145
### Message Usage Example
146

147
```java
148
import jakarta.mail.*;
149
import jakarta.mail.internet.*;
150

151
// Create message
152
MimeMessage message = new MimeMessage(session);
153

154
// Set addresses
155
message.setFrom(new InternetAddress("sender@example.com"));
156
message.setRecipients(Message.RecipientType.TO, 
157
    InternetAddress.parse("recipient1@example.com,recipient2@example.com"));
158
message.setRecipients(Message.RecipientType.CC, 
159
    InternetAddress.parse("cc@example.com"));
160

161
// Set subject and content
162
message.setSubject("Test Message");
163
message.setText("This is a test message body");
164

165
// Set sent date
166
message.setSentDate(new Date());
167

168
// Save changes before sending
169
message.saveChanges();
170
```
171

172
## Transport Operations
173

174
The Transport abstract class handles message transmission to recipients.
175

176
```java { .api }
177
public abstract class Transport extends Service {
178
    // Constructor
179
    public Transport(Session session, URLName urlname);
180
    
181
    // Static convenience methods
182
    public static void send(Message msg) throws MessagingException;
183
    public static void send(Message msg, Address[] addresses) throws MessagingException;
184
    public static void send(Message msg, String user, String password) throws MessagingException;
185
    public static void send(Message msg, Address[] addresses, String user, String password) throws MessagingException;
186
    
187
    // Instance methods
188
    public abstract void sendMessage(Message msg, Address[] addresses) throws MessagingException;
189
    
190
    // Event handling
191
    public void addTransportListener(TransportListener l);
192
    public void removeTransportListener(TransportListener l);
193
    
194
    // Service connection methods (inherited)
195
    public void connect() throws MessagingException;
196
    public void connect(String host, String user, String password) throws MessagingException;
197
    public void connect(String user, String password) throws MessagingException;
198
    public boolean isConnected();
199
    public void close() throws MessagingException;
200
}
201
```
202

203
### Transport Usage Example
204

205
```java
206
import jakarta.mail.*;
207
import jakarta.mail.internet.*;
208

209
// Simple send using static method
210
Transport.send(message);
211

212
// Send to specific addresses only
213
Address[] specificRecipients = {
214
    new InternetAddress("recipient@example.com")
215
};
216
Transport.send(message, specificRecipients);
217

218
// Using transport instance for multiple sends
219
Transport transport = session.getTransport("smtp");
220
try {
221
    transport.connect("smtp.gmail.com", username, password);
222
    transport.sendMessage(message1, message1.getAllRecipients());
223
    transport.sendMessage(message2, message2.getAllRecipients());
224
} finally {
225
    transport.close();
226
}
227
```
228

229
## Service Base Class
230

231
The Service abstract class provides common functionality for Store and Transport.
232

233
```java { .api }
234
public abstract class Service {
235
    // Connection management
236
    public void connect() throws MessagingException;
237
    public void connect(String host, String user, String password) throws MessagingException;
238
    public void connect(String user, String password) throws MessagingException;
239
    public boolean isConnected();
240
    public void close() throws MessagingException;
241
    
242
    // Service properties
243
    public URLName getURLName();
244
    public Session getSession();
245
    
246
    // Event handling
247
    public void addConnectionListener(ConnectionListener l);
248
    public void removeConnectionListener(ConnectionListener l);
249
    
250
    // String representation
251
    public String toString();
252
}
253
```
254

255
## Authentication Support
256

257
Jakarta Mail provides an authentication framework for secure connections.
258

259
```java { .api }
260
public abstract class Authenticator {
261
    // Override this method to provide authentication
262
    protected PasswordAuthentication getPasswordAuthentication();
263
    
264
    // Context information available during authentication
265
    protected String getDefaultUserName();
266
    protected String getRequestingPrompt();
267
    protected InetAddress getRequestingSite();
268
    protected int getRequestingPort();
269
    protected String getRequestingProtocol();
270
    protected String getRequestingScheme();
271
}
272

273
public final class PasswordAuthentication {
274
    public PasswordAuthentication(String userName, String password);
275
    public String getUserName();
276
    public String getPassword();
277
}
278
```
279

280
### Authentication Usage Example
281

282
```java
283
Authenticator auth = new Authenticator() {
284
    protected PasswordAuthentication getPasswordAuthentication() {
285
        // Could prompt user, read from config, etc.
286
        return new PasswordAuthentication("user@example.com", "password");
287
    }
288
};
289

290
Session session = Session.getInstance(props, auth);
291
```
292

293
## URL Name Support
294

295
URLName provides a structured way to represent mail server connection information.
296

297
```java { .api }
298
public class URLName {
299
    public URLName(String protocol, String host, int port, String file, 
300
                   String username, String password);
301
    public URLName(URL url);
302
    public URLName(String url);
303
    
304
    // Component access
305
    public String getProtocol();
306
    public String getHost();
307
    public int getPort();
308
    public String getFile();
309
    public String getUsername();
310
    public String getPassword();
311
    public String getRef();
312
    
313
    // URL operations
314
    public URL getURL() throws MalformedURLException;
315
    public String toString();
316
    public boolean equals(Object obj);
317
    public int hashCode();
318
}
319
```
320

321
### URLName Usage Example
322

323
```java
324
// Create URL name for IMAP connection
325
URLName url = new URLName("imaps", "imap.gmail.com", 993, null, "user@gmail.com", "password");
326

327
// Use with store
328
Store store = session.getStore(url);
329
store.connect();
330
```
331

332
## Provider Information
333

334
The Provider class describes available protocol implementations.
335

336
```java { .api }
337
public class Provider {
338
    public static final class Type {
339
        public static final Type STORE;
340
        public static final Type TRANSPORT;
341
        
342
        public String toString();
343
    }
344
    
345
    public Provider(Type type, String protocol, String className, String vendor, String version);
346
    
347
    public Type getType();
348
    public String getProtocol();
349
    public String getClassName();
350
    public String getVendor();
351
    public String getVersion();
352
    public String toString();
353
}
354
```
355

356
### Provider Usage Example
357

358
```java
359
// Get available providers
360
Provider[] providers = session.getProviders();
361
for (Provider provider : providers) {
362
    System.out.println("Protocol: " + provider.getProtocol());
363
    System.out.println("Type: " + provider.getType());
364
    System.out.println("Class: " + provider.getClassName());
365
}
366

367
// Get specific provider
368
Provider smtpProvider = session.getProvider("smtp");
369
```