mailparser for Node.js MIME email parsing

Where mailparser fits in an email processing service

mailparser addresses the point where an application receives a raw RFC-style email and needs its MIME structure decoded. That can include multipart bodies, character encodings, HTML, text alternatives, attachments, and references to embedded images. Instead of asking the rest of an application to interpret MIME boundaries, transfer encodings, and encoded words itself, mailparser turns the message into a structured JavaScript object.

The intended users are Node.js developers building mail ingestion, search, archiving, reporting, or automation services. The project is particularly relevant when the input may be large. Its README describes the parser as stream based and says this should allow it to process messages of 100 MB or more with relatively low overhead. That is a documented design claim, not a benchmark result. The repository also contains examples named `examples/pipe.js`, `examples/emailtojson.js`, and `examples/simple-async.js`, which reflects several common shapes: piped input, JSON-oriented output, and asynchronous parsing.

This is not a general-purpose email client library. Its stated scope is decoding MIME-formatted messages. It does not fetch mail from an inbox, identify threats, classify messages, or deliver mail. Those responsibilities belong elsewhere in an application. The package description is deliberately narrow: “Parse e-mails.”

Streaming MIME processing and parser entry points

The core architectural decision is to process email as a stream rather than require the complete message to be represented as one string before parsing begins. That matters for mailbox importers, file-based converters, and services that receive large messages through pipes. The repository includes `examples/pipe.js`, so piping input is an explicit supported direction rather than an incidental feature.

The package exposes the `MailParser` machinery and a `simpleParser` convenience API, as confirmed by the README's limits section. `simpleParser` can report completion through either a callback or a promise. Its contract is unusually specific: it invokes the callback or settles the promise exactly once. This detail matters when integrating error handling because a non-fatal parser error is not silently discarded.

The package dependencies indicate several parts of the decoding path. Its declared dependencies include `@zone-eu/mailsplit`, `libmime`, `iconv-lite`, `encoding-japanese`, `punycode.js`, `he`, `html-to-text`, and `linkify-it`. `nodemailer` is also a runtime dependency. Based on `package.json`, this is a Node.js package with its entry point at `index.js`, not a browser-first module.

Installing mailparser and loading its Node.js API

The README gives a direct npm installation path. The package requires Node.js 20.0.0 or newer according to `package.json`, so the runtime version should be checked before installation. The documented installation command is:

$ npm install mailparser

The expected result is a local `mailparser` dependency in the project's `node_modules` directory and corresponding metadata in the package manager's lockfile. The repository includes `package-lock.json`, although a new application should use the lockfile generated by its own package manager operation.

For CommonJS code, the README documents this import:

const mailparser = require('mailparser');

This loads the package object from its declared `index.js` entry point. It is the only complete JavaScript example in the README, so the repository does not provide enough inline guidance here to reproduce a full parse with a particular message source, callback shape, or option set. The README directs readers to the `mailparser` homepage for usage documentation and terms. Before writing a first parsing call, use that documentation to select either `simpleParser` or the lower-level `MailParser` flow and to confirm how the raw email will be supplied. The examples directory includes `examples/simple.js`, `examples/simple-async.js`, `examples/simple-options.js`, and corresponding `.eml` fixtures, which are the more concrete local references for a first use.

Embedded image inlining and the default 20 MB ceiling

One of the clearest operational constraints is HTML image handling. `simpleParser` replaces `cid:` image references in HTML with `data:` URLs. This is useful when the output must contain self-contained HTML rather than unresolved references to MIME parts. The resulting HTML grows as the URL representation of each embedded image is inserted.

The total inserted URL length is capped by `maxInlinedImagesSize`. Its default is 20 MB, measured in characters of the URLs written into the HTML. Once that limit is reached, remaining references stay as `cid:` links instead of being converted. A custom `updateImageLinks()` callback is subject to the same cap. This boundary matters for messages containing many or large inline images, because the returned HTML can be both memory-intensive and difficult to store or render.

The distinction between file size and character count is important. The documented limit concerns the generated URL text, not the original image attachment size. An application should therefore inspect actual output size and unresolved `cid:` references rather than assuming that every embedded image was converted. This behavior belongs to `simpleParser`; the README does not attribute it to every lower-level parser entry point.

Error delivery when HTML exceeds parser limits

mailparser has another sharp edge around non-fatal errors. The README gives `maxHtmlLengthToParse` as an example of a condition that can cause `MailParser` to report an error. When that happens, `simpleParser` passes the reported error to its callback or promise settlement. Despite the non-fatal classification, the caller receives the error rather than a clean completion result.

`MailParser` itself still emits the `'error'` event and then finishes parsing. That distinction can surprise code that treats every `'error'` event as proof that the parser stopped immediately, or that expects completion after `simpleParser` reports an error. The README does not document a continuation token or partial-result API in the cleanup, so an application should not assume that an error settlement exposes a complete parsed object.

Because `simpleParser` settles exactly once, a callback-based integration should avoid layering several competing completion paths around it. The project does not document retry behavior or automatic recovery in the README. Whether an oversized HTML field should be truncated, omitted, retained as raw content, or treated as a rejected job is therefore an application decision, not documented `mailparser` behavior.

Maintenance mode, release cadence, and PostalMime

The most significant adoption constraint is stated directly in the README: mailparser is in maintenance mode. It will continue to receive security updates and critical bug fixes, but the project will not receive new features or feature changes. The repository is not archived, and its last push was on 2026-10-16. Releases v3.9.37, v3.9.38, and v3.9.39 were published on 2026-10-08, 2026-10-10, and 2026-10-14 respectively. Those dates show recent releases, but they do not change the documented maintenance-mode boundary.

For new projects, the README recommends PostalMime. The stated difference is environment scope: PostalMime works in both Node.js and browser environments. mailparser is presented as an advanced parser for Node.js with streaming behavior, and `package.json` requires Node.js 20 or newer. PostalMime is therefore the more direct choice when browser execution is a requirement or when the developer wants to follow the maintainers' stated recommendation for a greenfield project.

mailparser remains relevant for applications that already depend on its output, use its streaming parser, or need its established MIME behavior. New feature requirements, however, should not be justified by choosing it merely because it remains available. Maintenance mode means expected work is limited to security and critical fixes.

Dependency and licensing checks before adoption

mailparser v3.9.39 declares `nodemailer` 10.1.1 as a runtime dependency, alongside MIME and text-conversion packages. That makes the full dependency footprint more than a single parser file. The package also specifies Node.js `>=20.0.0`, while the installation example uses npm and CommonJS `require('mailparser')`.

The license information requires attention. The repository classification says that the license is custom and cannot be classified by GitHub. In contrast, the README states “Licensed under MIT,” and `package.json` declares `"license": "MIT"`. The repository has a `LICENSE` file. That disagreement should be resolved by reading the actual `LICENSE` file and determining whether its terms match the MIT declarations before redistribution or integration into a product. This is a source-document check, not legal advice.

The upgrade path shown in `package.json` is an `update` script that removes `node_modules` and `package-lock.json`, runs `ncu -u`, and runs `npm install`. That script belongs to dependency maintenance inside the repository, not the documented installation procedure for an application. Application developers should not run it as a first-use step.

Editorial conclusion

mailparser is appropriate for Node.js services that must retain its existing parsing behavior, especially when compatibility with an installed Nodemailer ecosystem matters. It is a poor default for a new browser or Node.js parsing project because the README says that feature work has ended and points to PostalMime. Before adoption, inspect LICENSE because its classification conflicts with the MIT declarations in README.md and package.json, then verify Node.js 20 support and the required parsing behavior against the linked documentation.

Frequently asked questions

Official sources

1. Issues
2. nodemailer/mailparser on GitHub
3. README
4. Releases