mailparser

mailparser is a battle-tested Node.js library from the Nodemailer project that turns raw MIME-formatted email messages into structured JavaScript objects. It processes everything as a stream, so it can handle very large messages — including big attachments — with low memory overhead instead of buffering the entire email in memory first.

The library exposes both a low-level MailParser transform stream for advanced control and a simpleParser convenience function that resolves a fully parsed mail object in one call, including decoded text/HTML bodies, headers, address fields, and buffered attachments. It handles the gritty parts of email parsing automatically: charset decoding (including Japanese encodings via iconv-lite and encoding-japanese), quoted-printable/base64 transfer encodings, embedded/inline images, delivery-status reports, and RFC 2047 encoded headers.

What You Get

• A simpleParser function that returns a fully parsed mail object (subject, from/to/cc, text, html, attachments) from a Buffer, string, or readable stream in one call.
• A lower-level MailParser transform stream for processing very large messages (100MB+) without buffering the whole message in memory.
• Automatic character-set decoding for dozens of encodings, including specialized handling for Japanese encodings via encoding-japanese.
• Built-in handling for embedded/inline images, CID link rewriting to data URIs, delivery-status reports, and RFC 2047 encoded-word headers.
• Address parsing via Nodemailer’s addressparser, plus automatic plain-text-to-HTML and HTML-to-text conversion and link detection.

Common Use Cases

• Building an email-processing backend that ingests inbound mail (e.g. from an SMTP server or webhook) and extracts subject, sender, body, and attachments for storage or indexing.
• Parsing .eml files pulled from IMAP/POP3 mailboxes to build a webmail client, archiving tool, or compliance/eDiscovery pipeline.
• Extracting attachments from bulk-received emails for automated document processing (invoices, receipts, reports).
• Feeding raw email content into a spam-filtering, ticketing, or support-inbox system that needs structured header/body data rather than raw MIME.

Under The Hood

Architecture

mailparser is architected around a streaming MIME pipeline: the MailParser class (lib/mail-parser.js) extends Node’s Transform stream and pipes incoming data through a ChunkedPassthrough into a Splitter from the @zone-eu/mailsplit fork of mailsplit, which walks the MIME tree node by node. As each node arrives, MailParser tracks position in the tree (this.tree, this.curnode), attaches per-node charset decoders (IconvDecoder wrapping the node iconv library, or a custom JPDecoder for Japanese encodings via encoding-japanese), and emits ‘headers’ and object-mode ‘data’ events tagged type: ‘text’ or type: ‘attachment’ as content becomes available. lib/simple-parser.js is a thin, buffering wrapper: it drives a MailParser instance, accumulates attachment stream chunks into Buffers, and resolves a single flat mail object via callback or Promise, trading the streaming/low-memory advantage of the low-level API for ergonomics.

Tech Stack

The library is plain CommonJS JavaScript with no build/compile step and no TypeScript. Its runtime dependencies are narrowly scoped to MIME/email concerns: @zone-eu/mailsplit for MIME splitting, libmime for RFC 2047 header decoding, nodemailer’s internal addressparser for To/From/Cc parsing, iconv-lite and encoding-japanese for charset transcoding, html-to-text and linkify-it for text/HTML conversion and link detection, he for HTML entity handling, and tlds/punycode.js to support link detection and internationalized domains. Dev tooling is Grunt-based (grunt-contrib-nodeunit for tests) rather than a modern runner, with ESLint (nodemailer’s shared config) and Prettier for style, and an .ncurc.js config for automated dependency-update checks.

Code Quality

Test coverage is substantial: 13 test files under test/ (~2,100 lines) exercise the parser against real .eml fixtures, including dedicated regression tests named after specific GitHub issues (issue-221, issue-272, issue-337, issue-385, issue-412), plus focused suites for RFC822 headers-only messages, flowed text, delivery-status reports, long References headers, and address-security edge cases. There is no static typing (TypeScript or JSDoc-based), but error handling is deliberate: the JPDecoder’s charset conversion is wrapped in try/catch and falls back to passing raw bytes through on failure rather than throwing, and stream errors are surfaced via standard ‘error’ event propagation in both the low-level and simpleParser APIs.

API Design mailparser offers a two-tier API: simpleParser(input, options, callback) covers the common case with a single call that accepts a Buffer, string, or readable stream and resolves a fully-parsed mail object (Promise or callback), while the underlying MailParser transform stream is exposed directly for advanced consumers who need to process very large messages incrementally. Options are narrowly named and self-explanatory (skipHtmlToText, skipImageLinks, skipTextToHtml, keepCidLinks, keepDeliveryStatus), keeping boilerplate low. The main friction points are a thin README that defers full documentation to an external site (nodemailer.com/extras/mailparser) rather than inline docs, and the project’s maintenance-mode status, which points new adopters toward a separate project (PostalMime) for continued feature development.