postal-mime

library2.7.4jsnpmunverified

postal-mime is a robust and zero-dependency JavaScript library designed for parsing raw email messages in RFC822 format into a structured object. It operates effectively across Node.js, browser environments (including Web Workers), and serverless platforms like Cloudflare Email Workers. The library is currently stable at version 2.7.4, with a recent release cadence suggesting active maintenance and bug fixes, typically every few weeks or months. Key differentiators include its full TypeScript support, comprehensive handling of complex MIME structures (multipart messages, nested parts, attachments), built-in security limits to prevent Denial-of-Service attacks from malformed emails, and strict adherence to RFC 2822/5322 email standards. It differentiates itself by offering broad environment compatibility without external dependencies, making it a lightweight and versatile choice for email processing.

communication serialization http-networking

npm install postal-mime

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · POSTAL-MIME

postal-mime

communicationjavascriptv2.7.4

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

PostalMime

✓ import PostalMime from 'postal-mime';

✗ import { PostalMime } from 'postal-mime';

The `PostalMime` class is the default export for Node.js ESM. This is the primary way to use it in modern Node.js projects.

PostalMime

✓ const PostalMime = require('postal-mime');

✗ const { PostalMime } = require('postal-mime');

For CommonJS environments, `PostalMime` is directly available as the module export. CommonJS support was added in v2.6.0 and improved in v2.7.4 for bundler compatibility.

PostalMime

✓ import PostalMime from './node_modules/postal-mime/src/postal-mime.js';

✗ import PostalMime from 'postal-mime';

In browser environments, including Web Workers, the library must be imported directly from its source file path within `node_modules`.

✓ import type { Email } from 'postal-mime';

✗ import { Email } from 'postal-mime';

Always use `import type` for importing TypeScript interfaces or types to ensure they are stripped during compilation.

addressParser

✓ import { addressParser } from 'postal-mime';

✗ import PostalMime, { addressParser } from 'postal-mime';

Utility functions like `addressParser` are named exports, available for both ESM and CommonJS via destructuring.

Demonstrates parsing a basic email string with subject and HTML content, applying options, and logging the structured output using TypeScript in a Node.js environment.

import PostalMime from 'postal-mime'; import type { Email, PostalMimeOptions } from 'postal-mime'; import util from 'node:util'; async function parseEmail() { const options: PostalMimeOptions = { attachmentEncoding: 'base64' }; const rawEmail = `Subject: My awesome email 🤓\nContent-Type: text/html; charset=utf-8\n\n<p>Hello world 😵‍💫</p>`; const email: Email = await PostalMime.parse(rawEmail, options); console.log(`Parsed Subject: ${email.subject}`); console.log('Full Parsed Email Structure:'); // Use 'util.inspect' for pretty-printing in Node.js console.log(util.inspect(email, false, 22, true)); } parseEmail().catch(console.error);

Debug

Known issues

gotchaOlder versions of `postal-mime` (prior to v2.6.1 and v2.4.6) contained Denial-of-Service (DoS) vulnerabilities related to deeply nested address groups and excessively large MIME structures. Parsing malicious or malformed emails could lead to resource exhaustion.

fix

Upgrade to `postal-mime@2.6.1` or later to include critical security patches. Ensure your environment uses the latest patched version.

affects: <2.6.1

gotchaWhen parsing emails with potentially missing or malformed `Content-Type` or `Content-Disposition` headers, direct access to `.parsed` properties on `contentType` or `contentDisposition` fields could result in `TypeError: Cannot read properties of null`.

fix

Upgrade to `postal-mime@2.7.2` or newer, which includes explicit null checks. Alternatively, implement defensive coding by checking for `null` before accessing nested properties, e.g., `email.contentDisposition?.parsed?.parameters`.

affects: <2.7.2

gotchaPrior to v2.6.0, `postal-mime` primarily targeted ESM, causing issues with CommonJS `require()` in some environments or bundlers. Even after v2.6.0 (which added CJS support), certain bundler configurations might have encountered issues with `__esModule` and `.default` preservation until v2.7.4.

fix

For CommonJS usage, ensure you are on `postal-mime@2.7.4` or newer. If issues persist, verify your bundler's configuration for handling dual-package exports or prefer ESM imports where possible.

affects: <2.7.4

gotchaTypeScript type definitions have undergone several corrections and improvements across various versions. Older versions might have provided inaccurate or incomplete types, leading to compilation errors or unexpected runtime behavior despite correct JavaScript implementation.

fix

Always use the latest stable version of `postal-mime` for the most accurate and comprehensive TypeScript definitions. Review your code after upgrading to catch any new type errors that might reveal underlying logic issues due to previously incorrect typings.

affects: <2.7.3

gotchaBrowser environments require a specific import path (`./node_modules/postal-mime/src/postal-mime.js`) which can be brittle if `node_modules` path changes or if using certain bundler configurations without proper aliasing. Directly importing from the package name (`postal-mime`) will fail.

fix

Configure your bundler (e.g., Webpack, Rollup, Parcel) to alias `postal-mime` to its browser-specific path or ensure the relative path from your application entry point to `node_modules` is correct. For Web Workers, ensure the path resolution is handled correctly.

affects: *

Errors

Common errors & fixes

TypeError: Cannot read properties of null (reading 'parsed')

Attempting to access `.parsed` property on `contentType` or `contentDisposition` when it might be null or undefined due to missing or malformed headers in the email.

fix

Upgrade to `postal-mime@2.7.2` or newer. If not upgrading, defensively check for `null` or `undefined` before access, e.g., `email.contentType?.parsed?.parameters`.

PostalMime is not a constructor

Incorrect import method (e.g., named import for a default export) or CommonJS `require()` issues in environments that don't correctly handle dual-package exports, especially in versions before CJS support was robust.

fix

For ESM, ensure `import PostalMime from 'postal-mime';`. For CJS, use `const PostalMime = require('postal-mime');`. For browser environments, use the specific path `import PostalMime from './node_modules/postal-mime/src/postal-mime.js';`. Ensure you are on `v2.7.4` or later for best CJS compatibility.

Argument of type '...' is not assignable to parameter of type '...'.

Mismatch between the types inferred by the TypeScript compiler and the actual expected types, often due to outdated or incorrect type definitions shipped with older versions of the library.

fix

Upgrade to the latest version of `postal-mime` to benefit from updated and corrected TypeScript typings (e.g., `2.7.3`, `2.6.1`). Review your code for type assertions that might be masking actual type issues.

Upgrade

Version history

2.7.4latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

24 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/postalsys/postal-mime ↗

packagehttps://www.npmjs.com/package/postal-mime ↗

homepagehttps://postal-mime.postalsys.com ↗