0
# Internet Messaging
1

2
This document covers MIME message handling, Internet addressing, multipart content, and encoding utilities provided by the jakarta.mail.internet package.
3

4
## MIME Message Implementation
5

6
The MimeMessage class provides a concrete implementation of the Message interface with full MIME support.
7

8
### MimeMessage Creation
9

10
```java { .api }
11
class MimeMessage extends Message implements MimePart {
12
    MimeMessage(Session session);
13
    MimeMessage(Session session, InputStream is) throws MessagingException;
14
    MimeMessage(MimeMessage source) throws MessagingException;
15
}
16
```
17

18
**Parameters:**
19
- `session` (Session): Mail session for configuration
20
- `is` (InputStream): Stream containing RFC 822 message data
21
- `source` (MimeMessage): Source message for copying
22

23
### Address Handling
24

25
```java { .api }
26
class MimeMessage extends Message {
27
    public Address[] getFrom() throws MessagingException;
28
    public void setFrom() throws MessagingException;
29
    public void setFrom(Address address) throws MessagingException;
30
    public void setFrom(String address) throws MessagingException;
31
    public void addFrom(Address[] addresses) throws MessagingException;
32
    
33
    public Address[] getRecipients(RecipientType type) throws MessagingException;
34
    public void setRecipients(RecipientType type, Address[] addresses) throws MessagingException;
35
    public void setRecipients(RecipientType type, String addresses) throws MessagingException;
36
    public void addRecipients(RecipientType type, Address[] addresses) throws MessagingException;
37
    public void addRecipients(RecipientType type, String addresses) throws MessagingException;
38
    
39
    public Address[] getReplyTo() throws MessagingException;
40
    public void setReplyTo(Address[] addresses) throws MessagingException;
41
}
42
```
43

44
### Headers and Metadata
45

46
```java { .api }
47
class MimeMessage extends Message {
48
    public String getSubject() throws MessagingException;
49
    public void setSubject(String subject) throws MessagingException;
50
    public void setSubject(String subject, String charset) throws MessagingException;
51
    
52
    public Date getSentDate() throws MessagingException;
53
    public void setSentDate(Date d) throws MessagingException;
54
    public Date getReceivedDate() throws MessagingException;
55
    
56
    public String getMessageID() throws MessagingException;
57
    public void setHeader(String name, String value) throws MessagingException;
58
    public void addHeader(String name, String value) throws MessagingException;
59
    public void removeHeader(String name) throws MessagingException;
60
    public String[] getHeader(String name) throws MessagingException;
61
    public Enumeration<Header> getAllHeaders() throws MessagingException;
62
}
63
```
64

65
### Content Management
66

67
```java { .api }
68
class MimeMessage extends Message {
69
    public Object getContent() throws IOException, MessagingException;
70
    public void setContent(Object o, String type) throws MessagingException;
71
    public void setText(String text) throws MessagingException;
72
    public void setText(String text, String charset) throws MessagingException;
73
    public void setText(String text, String charset, String subtype) throws MessagingException;
74
    public void setContent(Multipart mp) throws MessagingException;
75
    
76
    public DataHandler getDataHandler() throws MessagingException;
77
    public void setDataHandler(DataHandler dh) throws MessagingException;
78
}
79
```
80

81
### Usage Example
82

83
```java
84
MimeMessage message = new MimeMessage(session);
85
message.setFrom(new InternetAddress("sender@example.com", "John Doe"));
86
// Alternative way to set from address using string
87
message.setFrom("sender@example.com");
88
message.setRecipients(Message.RecipientType.TO, "recipient@example.com");
89
message.setSubject("Hello World", "UTF-8");
90
message.setText("This is a test message with UTF-8 encoding.", "UTF-8", "plain");
91
message.setHeader("X-Priority", "1");
92
```
93

94
## Internet Address Handling
95

96
The InternetAddress class handles RFC 822/2822 compliant email addresses with personal name support.
97

98
### Address Creation
99

100
```java { .api }
101
class InternetAddress extends Address implements Cloneable {
102
    InternetAddress();
103
    InternetAddress(String address) throws AddressException;
104
    InternetAddress(String address, boolean strict) throws AddressException;
105
    InternetAddress(String address, String personal) throws UnsupportedEncodingException;
106
    InternetAddress(String address, String personal, String charset) throws UnsupportedEncodingException;
107
}
108
```
109

110
**Parameters:**
111
- `address` (String): Email address (e.g., "user@example.com")
112
- `strict` (boolean): Enable strict RFC 822 parsing
113
- `personal` (String): Display name for the address
114
- `charset` (String): Character encoding for personal name
115

116
### Address Properties
117

118
```java { .api }
119
class InternetAddress extends Address {
120
    String getAddress();
121
    void setAddress(String address);
122
    String getPersonal();
123
    void setPersonal(String name) throws UnsupportedEncodingException;
124
    void setPersonal(String name, String charset) throws UnsupportedEncodingException;
125
    
126
    String toString();
127
    String toUnicodeString();
128
    boolean equals(Object a);
129
    int hashCode();
130
    Object clone();
131
}
132
```
133

134
### Address Parsing and Validation
135

136
```java { .api }
137
class InternetAddress extends Address {
138
    static InternetAddress[] parse(String addresslist) throws AddressException;
139
    static InternetAddress[] parse(String addresslist, boolean strict) throws AddressException;
140
    static InternetAddress[] parseHeader(String addresslist, boolean strict) throws AddressException;
141
    
142
    void validate() throws AddressException;
143
    boolean isGroup();
144
    InternetAddress[] getGroup(boolean strict) throws AddressException;
145
    
146
    static String toString(Address[] addresses);
147
    static String toString(Address[] addresses, int used);
148
}
149
```
150

151
### Usage Examples
152

153
```java
154
// Simple address
155
InternetAddress addr1 = new InternetAddress("user@example.com");
156

157
// Address with personal name
158
InternetAddress addr2 = new InternetAddress("user@example.com", "John Doe");
159

160
// Parse multiple addresses
161
InternetAddress[] addresses = InternetAddress.parse("user1@example.com, John Doe <user2@example.com>");
162

163
// Validate address format
164
try {
165
    addr1.validate();
166
} catch (AddressException e) {
167
    System.err.println("Invalid address: " + e.getMessage());
168
}
169

170
// Convert addresses to string
171
String addressList = InternetAddress.toString(addresses);
172
```
173

174
## News Address Handling
175

176
The NewsAddress class handles Usenet newsgroup addresses.
177

178
```java { .api }
179
class NewsAddress extends Address {
180
    NewsAddress();
181
    NewsAddress(String newsgroup);
182
    NewsAddress(String newsgroup, String host);
183
    
184
    String getNewsgroup();
185
    void setNewsgroup(String newsgroup);
186
    String getHost();
187
    void setHost(String host);
188
    
189
    static NewsAddress[] parse(String newsgroups) throws AddressException;
190
    
191
    String getType();
192
    String toString();
193
    boolean equals(Object a);
194
    int hashCode();
195
}
196
```
197

198
## MIME Body Parts
199

200
The MimeBodyPart class represents individual parts within a multipart message.
201

202
### BodyPart Creation
203

204
```java { .api }
205
class MimeBodyPart extends BodyPart implements MimePart {
206
    MimeBodyPart();
207
    MimeBodyPart(InputStream is) throws MessagingException;
208
    MimeBodyPart(InternetHeaders headers, byte[] content) throws MessagingException;
209
}
210
```
211

212
### Content Management
213

214
```java { .api }
215
class MimeBodyPart extends BodyPart {
216
    public Object getContent() throws IOException, MessagingException;
217
    public void setContent(Object o, String type) throws MessagingException;
218
    public void setText(String text) throws MessagingException;
219
    public void setText(String text, String charset) throws MessagingException;
220
    public void setText(String text, String charset, String subtype) throws MessagingException;
221
    public void setContent(Multipart mp) throws MessagingException;
222
    
223
    public DataHandler getDataHandler() throws MessagingException;
224
    public void setDataHandler(DataHandler dh) throws MessagingException;
225
}
226
```
227

228
### File Attachments
229

230
```java { .api }
231
class MimeBodyPart extends BodyPart {
232
    public void attachFile(File file) throws IOException, MessagingException;
233
    public void attachFile(String file) throws IOException, MessagingException;
234
    public void attachFile(File file, String contentType, String encoding) throws IOException, MessagingException;
235
    
236
    public void saveFile(File file) throws IOException, MessagingException;
237
    public void saveFile(String file) throws IOException, MessagingException;
238
}
239
```
240

241
### Headers and Properties
242

243
```java { .api }
244
class MimeBodyPart extends BodyPart {
245
    public String[] getHeader(String name) throws MessagingException;
246
    public void setHeader(String name, String value) throws MessagingException;
247
    public void addHeader(String name, String value) throws MessagingException;
248
    public void removeHeader(String name) throws MessagingException;
249
    public Enumeration<Header> getAllHeaders() throws MessagingException;
250
    
251
    public String getDisposition() throws MessagingException;
252
    public void setDisposition(String disposition) throws MessagingException;
253
    public String getFileName() throws MessagingException;
254
    public void setFileName(String filename) throws MessagingException;
255
    public void setContentID(String cid) throws MessagingException;
256
}
257
```
258

259
### Usage Example
260

261
```java
262
MimeBodyPart textPart = new MimeBodyPart();
263
textPart.setText("This is the message body.", "UTF-8");
264

265
MimeBodyPart attachmentPart = new MimeBodyPart();
266
attachmentPart.attachFile(new File("/path/to/document.pdf"));
267
attachmentPart.setFileName("document.pdf");
268
attachmentPart.setDisposition(Part.ATTACHMENT);
269
attachmentPart.setContentID("<attachment@example.com>");
270
```
271

272
## Multipart Messages
273

274
The MimeMultipart class handles messages with multiple parts (text, attachments, etc.).
275

276
### Multipart Creation
277

278
```java { .api }
279
class MimeMultipart extends Multipart {
280
    MimeMultipart() throws MessagingException;
281
    MimeMultipart(String subtype) throws MessagingException;
282
    MimeMultipart(DataSource ds) throws MessagingException;
283
    MimeMultipart(String subtype, String boundary) throws MessagingException;
284
    MimeMultipart(BodyPart... parts) throws MessagingException;
285
    MimeMultipart(String subtype, BodyPart... parts) throws MessagingException;
286
}
287
```
288

289
**Parameters:**
290
- `subtype` (String): Multipart subtype (e.g., "mixed", "alternative", "related")
291
- `ds` (DataSource): Data source containing multipart data
292
- `boundary` (String): Custom boundary string for parts separation
293
- `parts` (BodyPart...): Variable arguments list of body parts to include
294

295
**Common Subtypes:**
296
- `"mixed"` - Default for messages with attachments
297
- `"alternative"` - Alternative representations (text/html)
298
- `"related"` - Related parts (HTML with embedded images)
299

300
### Part Management
301

302
```java { .api }
303
class MimeMultipart extends Multipart {
304
    public void addBodyPart(BodyPart part) throws MessagingException;
305
    public void addBodyPart(BodyPart part, int index) throws MessagingException;
306
    public void removeBodyPart(int index) throws MessagingException;
307
    public void removeBodyPart(BodyPart part) throws MessagingException;
308
    
309
    public BodyPart getBodyPart(int index) throws MessagingException;
310
    public int getCount() throws MessagingException;
311
    
312
    public boolean isComplete() throws MessagingException;
313
    public String getPreamble() throws MessagingException;
314
    public void setPreamble(String preamble) throws MessagingException;
315
}
316
```
317

318
### Usage Example
319

320
```java
321
// Create multipart message with text and attachment
322
MimeMultipart multipart = new MimeMultipart("mixed");
323

324
// Add text part
325
MimeBodyPart textPart = new MimeBodyPart();
326
textPart.setText("Please find the attachment.", "UTF-8");
327
multipart.addBodyPart(textPart);
328

329
// Add attachment
330
MimeBodyPart attachmentPart = new MimeBodyPart();
331
attachmentPart.attachFile("/path/to/file.doc");
332
multipart.addBodyPart(attachmentPart);
333

334
// Set multipart content to message
335
message.setContent(multipart);
336

337
// Alternative: Create multipart with varargs constructor
338
MimeBodyPart textPart2 = new MimeBodyPart();
339
textPart2.setText("Another message body.", "UTF-8");
340
MimeBodyPart attachmentPart2 = new MimeBodyPart();
341
attachmentPart2.attachFile("/path/to/another.doc");
342

343
MimeMultipart multipart2 = new MimeMultipart("mixed", textPart2, attachmentPart2);
344
```
345

346
## MIME Utility Functions
347

348
The MimeUtility class provides encoding, decoding, and MIME manipulation utilities.
349

350
### Encoding and Decoding
351

352
```java { .api }
353
class MimeUtility {
354
    static String getEncoding(DataHandler dh);
355
    static String getEncoding(DataSource ds);
356
    
357
    static InputStream decode(InputStream is, String encoding) throws MessagingException;
358
    static OutputStream encode(OutputStream os, String encoding) throws MessagingException;
359
    static OutputStream encode(OutputStream os, String encoding, String filename) throws MessagingException;
360
}
361
```
362

363
### Text Encoding
364

365
```java { .api }
366
class MimeUtility {
367
    static String encodeText(String text) throws UnsupportedEncodingException;
368
    static String encodeText(String text, String charset, String encoding) throws UnsupportedEncodingException;
369
    static String decodeText(String etext) throws UnsupportedEncodingException;
370
    
371
    static String encodeWord(String word) throws UnsupportedEncodingException;
372
    static String encodeWord(String word, String charset, String encoding) throws UnsupportedEncodingException;
373
    static String decodeWord(String eword) throws ParseException, UnsupportedEncodingException;
374
}
375
```
376

377
### Header Utilities
378

379
```java { .api }
380
class MimeUtility {
381
    static String quote(String word, String specials);
382
    static String fold(int used, String s);
383
    static String unfold(String s);
384
    
385
    static boolean isMimeType(String mimeType, String match);
386
    static String cleanContentType(MimePart mp, String contentType);
387
}
388
```
389

390
### Usage Examples
391

392
```java
393
// Encode non-ASCII text for headers
394
String encoded = MimeUtility.encodeText("Héllo Wörld", "UTF-8", "B");
395

396
// Decode encoded header text
397
String decoded = MimeUtility.decodeText("=?UTF-8?B?SMOpbGxvIFfDtnJsZA==?=");
398

399
// Check MIME type
400
boolean isText = MimeUtility.isMimeType("text/plain", "text/*");
401

402
// Fold long header lines
403
String folded = MimeUtility.fold(0, "Very long header value that needs to be folded");
404
```
405

406
## Header Management
407

408
The InternetHeaders class provides storage and manipulation of RFC 822 headers.
409

410
### Header Creation
411

412
```java { .api }
413
class InternetHeaders {
414
    InternetHeaders();
415
    InternetHeaders(InputStream is) throws MessagingException;
416
}
417
```
418

419
### Header Operations
420

421
```java { .api }
422
class InternetHeaders {
423
    void load(InputStream is) throws MessagingException;
424
    
425
    String[] getHeader(String name);
426
    String getHeader(String name, String delimiter);
427
    void setHeader(String name, String value);
428
    void addHeader(String name, String value);
429
    void removeHeader(String name);
430
    
431
    Enumeration<Header> getAllHeaders();
432
    Enumeration<Header> getMatchingHeaders(String[] names);
433
    Enumeration<Header> getNonMatchingHeaders(String[] names);
434
    
435
    void addHeaderLine(String line);
436
}
437
```
438

439
### Header Class
440

441
```java { .api }
442
class Header {
443
    Header(String name, String value);
444
    String getName();
445
    String getValue();
446
}
447
```
448

449
## Content Type Handling
450

451
The ContentType class represents and parses Content-Type headers.
452

453
### ContentType Creation
454

455
```java { .api }
456
class ContentType {
457
    ContentType();
458
    ContentType(String s) throws ParseException;
459
    ContentType(String primaryType, String subType, ParameterList list);
460
}
461
```
462

463
### Type Information
464

465
```java { .api }
466
class ContentType {
467
    String getPrimaryType();
468
    String getSubType();
469
    String getBaseType();
470
    
471
    String getParameter(String name);
472
    void setParameter(String name, String value);
473
    ParameterList getParameterList();
474
    void setParameterList(ParameterList list);
475
    
476
    boolean match(ContentType cType);
477
    boolean match(String s);
478
    
479
    String toString();
480
}
481
```
482

483
### Usage Example
484

485
```java
486
ContentType ct = new ContentType("text/plain; charset=UTF-8");
487
System.out.println("Primary: " + ct.getPrimaryType()); // "text"
488
System.out.println("Sub: " + ct.getSubType());         // "plain"
489
System.out.println("Charset: " + ct.getParameter("charset")); // "UTF-8"
490
```
491

492
## Content Disposition
493

494
The ContentDisposition class handles Content-Disposition headers for attachments.
495

496
```java { .api }
497
class ContentDisposition {
498
    ContentDisposition();
499
    ContentDisposition(String s) throws ParseException;
500
    ContentDisposition(String disposition, ParameterList list);
501
    
502
    String getDisposition();
503
    String getParameter(String name);
504
    void setParameter(String name, String value);
505
    ParameterList getParameterList();
506
    void setParameterList(ParameterList list);
507
    
508
    String toString();
509
}
510
```
511

512
## Parameter Lists
513

514
The ParameterList class manages parameter lists in MIME headers.
515

516
```java { .api }
517
class ParameterList {
518
    ParameterList();
519
    ParameterList(String s) throws ParseException;
520
    
521
    int size();
522
    String get(String name);
523
    void set(String name, String value);
524
    void set(String name, String value, String charset);
525
    void remove(String name);
526
    
527
    Enumeration<String> getNames();
528
    String toString();
529
    String toString(int used);
530
}
531
```
532

533
## Header Tokenizer
534

535
The HeaderTokenizer class parses RFC 822 header values into tokens.
536

537
### Tokenizer Creation
538

539
```java { .api }
540
class HeaderTokenizer {
541
    HeaderTokenizer(String header);
542
    HeaderTokenizer(String header, String delimiters);
543
    HeaderTokenizer(String header, String delimiters, boolean skipComments);
544
}
545
```
546

547
### Token Operations
548

549
```java { .api }
550
class HeaderTokenizer {
551
    Token next() throws ParseException;
552
    Token peek() throws ParseException;
553
    String getRemainder();
554
    
555
    static class Token {
556
        static final int ATOM = -1;
557
        static final int QUOTEDSTRING = -2;
558
        static final int COMMENT = -3;
559
        static final int EOF = -4;
560
        
561
        int getType();
562
        String getValue();
563
    }
564
}
565
```
566

567
## MIME Interfaces
568

569
### MimePart Interface
570

571
```java { .api }
572
interface MimePart extends Part {
573
    String getEncoding() throws MessagingException;
574
    String getContentID() throws MessagingException;
575
    String getContentMD5() throws MessagingException;
576
    void setContentMD5(String md5) throws MessagingException;
577
    String[] getContentLanguage() throws MessagingException;
578
    void setContentLanguage(String[] languages) throws MessagingException;
579
    
580
    void setText(String text, String charset) throws MessagingException;
581
    void setContent(Object o, String type) throws MessagingException;
582
}
583
```
584

585
### SharedInputStream Interface
586

587
```java { .api }
588
interface SharedInputStream {
589
    long getPosition();
590
    InputStream newStream(long start, long end);
591
}
592
```
593

594
## Exception Classes
595

596
```java { .api }
597
class AddressException extends ParseException {
598
    AddressException();
599
    AddressException(String s);
600
    AddressException(String s, String ref);
601
    AddressException(String s, String ref, int pos);
602
    
603
    String getRef();
604
    int getPos();
605
}
606

607
class ParseException extends MessagingException {
608
    ParseException();
609
    ParseException(String s);
610
}
611
```
612

613
### Error Handling Example
614

615
```java
616
try {
617
    InternetAddress[] addresses = InternetAddress.parse("invalid-email");
618
} catch (AddressException e) {
619
    System.err.println("Address parsing failed: " + e.getMessage());
620
    System.err.println("At position: " + e.getPos());
621
    System.err.println("Reference: " + e.getRef());
622
}
623
```