0
# Mailparser
1
2
Mailparser is an advanced email parser for Node.js that handles email parsing as a stream, making it capable of processing very large messages (100MB+) with relatively low overhead. It provides comprehensive email parsing capabilities including header extraction, body parsing, attachment handling, and support for various email encodings and formats.
3
4
## Package Information
5
6
- **Package Name**: mailparser
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install mailparser`
10
11
## Core Imports
12
13
```javascript
14
const { MailParser, simpleParser } = require('mailparser');
15
```
16
17
For ES modules:
18
19
```javascript
20
import { MailParser, simpleParser } from 'mailparser';
21
```
22
23
## Basic Usage
24
25
```javascript
26
const { simpleParser } = require('mailparser');
27
const fs = require('fs');
28
29
// Parse email from file
30
simpleParser(fs.createReadStream('email.eml'))
31
.then(mail => {
32
console.log(mail.subject);
33
console.log(mail.text);
34
console.log(mail.attachments.length);
35
})
36
.catch(err => {
37
console.error(err);
38
});
39
40
// Parse email from string
41
const emailString = 'From: sender@example.com...';
42
simpleParser(emailString)
43
.then(mail => {
44
console.log(mail.from.text);
45
console.log(mail.html);
46
});
47
```
48
49
## Architecture
50
51
Mailparser is built around two main components:
52
53
- **Simple Parser**: `simpleParser` function for one-shot parsing with automatic attachment handling
54
- **Streaming Parser**: `MailParser` class for advanced streaming scenarios with event-based processing
55
- **Stream Processing**: Memory-efficient parsing using Node.js streams for large email handling
56
- **Character Encoding**: Comprehensive support for various character encodings including Japanese encodings
57
- **Attachment Handling**: Stream-based attachment processing with checksums and metadata
58
59
## Capabilities
60
61
### Simple Email Parsing
62
63
High-level email parsing function that handles the complete parsing process and returns a structured mail object with all content and attachments.
64
65
```javascript { .api }
66
function simpleParser(
67
input: string | Buffer | Stream,
68
options?: ParseOptions,
69
callback?: (err: Error | null, mail: ParsedMail) => void
70
): Promise<ParsedMail>;
71
72
interface ParseOptions {
73
keepCidLinks?: boolean;
74
skipHtmlToText?: boolean;
75
skipImageLinks?: boolean;
76
skipTextToHtml?: boolean;
77
skipTextLinks?: boolean;
78
keepDeliveryStatus?: boolean;
79
Iconv?: any;
80
checksumAlgo?: string;
81
maxHtmlLengthToParse?: number;
82
formatDateString?: (date: Date) => string;
83
}
84
85
interface ParsedMail {
86
headers: Map<string, any>;
87
headerLines: HeaderLine[];
88
html?: string;
89
text?: string;
90
textAsHtml?: string;
91
subject?: string;
92
date?: Date;
93
from?: AddressObject;
94
to?: AddressObject;
95
cc?: AddressObject;
96
bcc?: AddressObject;
97
messageId?: string;
98
inReplyTo?: string;
99
replyTo?: AddressObject;
100
references?: string[];
101
attachments: Attachment[];
102
}
103
```
104
105
[Simple Email Parsing](./simple-parser.md)
106
107
### Streaming Email Parsing
108
109
Low-level streaming parser class for advanced email processing scenarios where you need fine-grained control over the parsing process and event handling.
110
111
```javascript { .api }
112
class MailParser extends Transform {
113
constructor(options?: ParseOptions);
114
115
// Event listeners for Transform stream
116
on(event: 'headers', listener: (headers: Map<string, any>) => void): this;
117
on(event: 'readable', listener: () => void): this;
118
on(event: 'end', listener: () => void): this;
119
on(event: 'error', listener: (err: Error) => void): this;
120
121
// Stream reading method
122
read(): TextData | AttachmentData | null;
123
}
124
125
interface TextData {
126
type: 'text';
127
html?: string;
128
text?: string;
129
textAsHtml?: string;
130
}
131
132
interface AttachmentData {
133
type: 'attachment';
134
content: Stream;
135
contentType: string;
136
filename?: string;
137
contentDisposition?: string;
138
contentId?: string;
139
headers: Map<string, any>;
140
checksum?: string;
141
size?: number;
142
release(): void;
143
}
144
```
145
146
[Streaming Email Parsing](./mail-parser.md)
147
148
## Types
149
150
```javascript { .api }
151
interface HeaderLine {
152
key: string;
153
line: string;
154
}
155
156
interface AddressObject {
157
value: Address[];
158
html: string;
159
text: string;
160
}
161
162
interface Address {
163
name?: string;
164
address: string;
165
group?: Address[];
166
}
167
168
interface Attachment {
169
type: 'attachment';
170
content: Buffer;
171
contentType: string;
172
partId?: string;
173
contentDisposition?: string;
174
filename?: string;
175
contentId?: string;
176
cid?: string;
177
related?: boolean;
178
headers: Map<string, any>;
179
checksum?: string;
180
size?: number;
181
}
182
```