0
# Simple Email Parsing
1

2
High-level email parsing function that handles the complete parsing process and returns a structured mail object with all content and attachments. This is the recommended approach for most use cases.
3

4
## Capabilities
5

6
### simpleParser Function
7

8
Parses email data and returns a complete mail object with all parsed content, headers, and attachments.
9

10
```javascript { .api }
11
/**
12
 * Parse email data into a structured mail object
13
 * @param input - Email data as string, Buffer, or readable stream
14
 * @param options - Optional parsing configuration
15
 * @param callback - Optional callback function (if not provided, returns Promise)
16
 * @returns Promise resolving to parsed mail object
17
 */
18
function simpleParser(
19
  input: string | Buffer | Stream,
20
  options?: ParseOptions,
21
  callback?: (err: Error | null, mail: ParsedMail) => void
22
): Promise<ParsedMail>;
23
```
24

25
**Usage Examples:**
26

27
```javascript
28
const { simpleParser } = require('mailparser');
29
const fs = require('fs');
30

31
// Parse from file stream
32
const mail = await simpleParser(fs.createReadStream('message.eml'));
33
console.log(mail.subject);
34
console.log(mail.from.text);
35
console.log(mail.attachments.length);
36

37
// Parse from string with options
38
const emailString = `From: sender@example.com
39
To: recipient@example.com
40
Subject: Test Message
41

42
Hello World!`;
43

44
const mail = await simpleParser(emailString, {
45
  skipHtmlToText: true,
46
  keepCidLinks: true
47
});
48

49
// Parse with callback style
50
simpleParser(emailBuffer, (err, mail) => {
51
  if (err) {
52
    console.error('Parse error:', err);
53
    return;
54
  }
55
  console.log('Subject:', mail.subject);
56
  console.log('Text:', mail.text);
57
});
58
```
59

60
### Parse Options
61

62
Configuration options for controlling parsing behavior.
63

64
```javascript { .api }
65
interface ParseOptions {
66
  /** Keep CID links in HTML instead of converting to base64 data URLs */
67
  keepCidLinks?: boolean;
68
  /** Skip converting HTML content to plain text */
69
  skipHtmlToText?: boolean;
70
  /** Skip processing image src attributes */
71
  skipImageLinks?: boolean;
72
  /** Skip converting plain text to HTML */
73
  skipTextToHtml?: boolean;
74
  /** Skip auto-linking URLs in plain text */
75
  skipTextLinks?: boolean;
76
  /** Keep message/delivery-status parts as text instead of ignoring */
77
  keepDeliveryStatus?: boolean;
78
  /** Custom Iconv instance for character encoding */
79
  Iconv?: any;
80
  /** Algorithm for calculating attachment checksums (default: 'md5') */
81
  checksumAlgo?: string;
82
  /** Maximum HTML content length to parse (prevents memory issues) */
83
  maxHtmlLengthToParse?: number;
84
  /** Custom function for formatting date strings */
85
  formatDateString?: (date: Date) => string;
86
}
87
```
88

89
### Parsed Mail Object
90

91
The complete structure returned by simpleParser containing all parsed email data.
92

93
```javascript { .api }
94
interface ParsedMail {
95
  /** Map of all email headers (case-insensitive keys) */
96
  headers: Map<string, any>;
97
  /** Array of raw header lines as received */
98
  headerLines: HeaderLine[];
99
  /** HTML content of the email */
100
  html?: string;
101
  /** Plain text content of the email */
102
  text?: string;
103
  /** Plain text converted to HTML format */
104
  textAsHtml?: string;
105
  /** Email subject line */
106
  subject?: string;
107
  /** Parsed date from Date header */
108
  date?: Date;
109
  /** Parsed From addresses */
110
  from?: AddressObject;
111
  /** Parsed To addresses */
112
  to?: AddressObject;
113
  /** Parsed CC addresses */
114
  cc?: AddressObject;
115
  /** Parsed BCC addresses */
116
  bcc?: AddressObject;
117
  /** Message-ID header value */
118
  messageId?: string;
119
  /** In-Reply-To header value */
120
  inReplyTo?: string;
121
  /** Reply-To addresses */
122
  replyTo?: AddressObject;
123
  /** References header values as array */
124
  references?: string[];
125
  /** Array of all attachments found in the email */
126
  attachments: Attachment[];
127
}
128
```
129

130
### Error Handling
131

132
```javascript
133
// The function throws TypeError for invalid input
134
try {
135
  await simpleParser(null); // Throws TypeError
136
} catch (err) {
137
  console.error(err.message); // "Input cannot be null or undefined."
138
}
139

140
// Parse errors are returned/thrown normally
141
try {
142
  const mail = await simpleParser(corruptedEmailData);
143
} catch (err) {
144
  console.error('Failed to parse email:', err);
145
}
146
```
147

148
### Input Types
149

150
The simpleParser function accepts three types of input:
151

152
- **String**: Raw email content as text
153
- **Buffer**: Email data as binary buffer
154
- **Stream**: Readable stream containing email data
155

156
```javascript
157
// String input
158
await simpleParser('From: test@example.com\n\nHello');
159

160
// Buffer input  
161
const buffer = Buffer.from(emailString, 'utf8');
162
await simpleParser(buffer);
163

164
// Stream input
165
const stream = fs.createReadStream('email.eml');
166
await simpleParser(stream);
167
```