MailParser
Streaming e‑mail parser for Node.js that can handle very large messages with minimal memory overhead.
MailParser offers two ways to consume a message:
simpleParser
– convenience helper that buffers the whole message (including attachments) in memory and returns a single mail object. Great for simple use‑cases and tests.MailParser
class – a lower‑levelTransform
stream that emits message parts and attachment streams as they become available, letting you process huge messages without blowing up memory.
Installation
npm install mailparser
simpleParser()
const { simpleParser } = require("mailparser");
// Callback style
simpleParser(source, options, (err, mail) => {
if (err) throw err;
console.log(mail.subject);
});
// Promise style
simpleParser(source, options)
.then((mail) => console.log(mail.subject))
.catch(console.error);
// async/await
const mail = await simpleParser(source, options);
Parameters
source
– aBuffer
,String
, or readable stream containing the RFC 822 message.options
– optional configuration (see Options).
Returned mail object
The resolved mail
object aggregates every piece of the message:
Property | Type/Notes |
---|---|
headers | Map of lowercase header keys → parsed values |
subject | String – shorthand for headers.get('subject') |
from , to , cc , bcc , reply-to | Address object (see below) |
date | Date object |
messageId | String |
inReplyTo | String |
references | String[] | String |
html | HTML body with cid: images inlined as data URIs |
text | Plain‑text body |
textAsHtml | text rendered as basic HTML |
attachments | Attachment[] (buffered in memory) |
No sanitisation is performed. If you display html
, make sure to run it through a trusted HTML‑sanitiser first.
Address object
{
"value": [
{
"name": "Jane Doe",
"address": "jane@example.com"
}
],
"html": "<span class=\"mp_address_name\">Jane Doe</span> <<a href=\"mailto:jane@example.com\" class=\"mp_address_email\">jane@example.com</a>>",
"text": "Jane Doe <jane@example.com>"
}
value
– array of individual addresses (or groups)text
– formatted for plaintext contexthtml
– formatted for HTML context
For a deep‑dive into address objects see the Message → Addresses section.
headers
Map quirks
Most headers resolve to strings (single header) or string[] (multiple occurrences). The following are parsed into richer structures for convenience:
- Address headers → address objects (
from
,to
,cc
,bcc
,sender
,reply-to
,delivered-to
,return-path
). - Priority headers (
x-priority
,importance
, …) are normalised to a singlepriority
key with values"high" | "normal" | "low"
. references
→String
|String[]
.date
→Date
.- Structured headers (
content-type
,content-disposition
,dkim-signature
) →{ value: String, params: Object }
.
Attachment object (simpleParser)
Property | Notes |
---|---|
filename | File name (may be undefined ) |
contentType | MIME type |
contentDisposition | Usually "attachment" |
checksum | MD5 hash of content |
size | Bytes |
headers | Map of MIME headers for this node |
content | Buffer with the entire attachment |
contentId / cid | Content‑ID (without angle brackets) |
related | true if the part is inline (eg. embedded image) |
MailParser
(stream API)
const { MailParser } = require("mailparser");
const parser = new MailParser(options);
sourceStream.pipe(parser);
MailParser
is a Transform
stream in object mode that emits two kinds of objects via the 'data'
event:
{ type: 'headers', headers: Map }
– once, after the headers are parsed.{ type: 'attachment', ... }
– for every attachment (see below). Thecontent
property is a Readable stream.{ type: 'text', html, text, textAsHtml }
– once, containing the message bodies.
Stream options
Option | Default | Description |
---|---|---|
skipHtmlToText | false | Do not generate text from HTML |
maxHtmlLengthToParse | Infinity | Limit HTML size in bytes |
formatDateString | undefined | Custom date → string formatter |
skipImageLinks | false | Leave cid: links untouched |
skipTextToHtml | false | Do not generate textAsHtml |
skipTextLinks | false | Skip link‑autodetection in text |
keepDeliveryStatus | false | Treat message/delivery-status parts as attachments |
Iconv | iconv-lite | Alternative iconv implementation |
keepCidLinks | false | simpleParser‑only – synonym for skipImageLinks: true |
Attachment stream object (type === 'attachment'
)
Identical shape to the buffered object shown earlier, except:
content
is a Readable stream.- You must call
attachment.release()
when you are done. Parsing pauses until every attachment is released. related
is only available after parsing ends.
parser.on("data", (part) => {
if (part.type === "attachment") {
console.log("Attachment:", part.filename);
part.content.pipe(fs.createWriteStream(part.filename)).on("finish", part.release);
}
});
Character set decoding
MailParser relies on iconv‑lite for charset conversion, except for ISO‑2022‑JP and EUC‑JP which are handled by encoding‑japanese.
If you prefer node-iconv
, inject it:
const { Iconv } = require('iconv');
const { simpleParser } = require('mailparser');
simpleParser(rfc822Message, { Iconv })
.then(mail => /* … */);
License
Dual‑licensed under the MIT License or EUPL v1.1 +.