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
```