Package detail

postal-mime

postalsys227.1kMIT-02.5.0

Email parser for browser environments

mime, email

readme

postal-mime

postal-mime is an email parsing library that runs in browser environments (including Web Workers) and serverless functions (like Cloudflare Email Workers). It takes in a raw email message (RFC822 format) and outputs a structured object containing headers, recipients, attachments, and more.

[!TIP] PostalMime is developed by the makers of EmailEngine—a self-hosted email gateway that provides a REST API for IMAP and SMTP servers and sends webhooks whenever something changes in registered accounts.

Features

  • Browser & Node.js compatible - Works in browsers, Web Workers, Node.js, and serverless environments
  • TypeScript support - Fully typed with comprehensive type definitions
  • Zero dependencies - No external dependencies
  • RFC compliant - Follows RFC 2822/5322 email standards
  • Handles complex MIME structures - Multipart messages, nested parts, attachments
  • Security limits - Built-in protection against deeply nested messages and oversized headers

Table of Contents


Source

The source code is available on GitHub.

Demo

Try out a live demo using the example page.

Installation

Install the module from npm:

npm install postal-mime

Usage

You can import the PostalMime class differently depending on your environment:

Browser

To use PostalMime in the browser (including Web Workers), import it from the src folder:

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

const email = await PostalMime.parse(`Subject: My awesome email 🤓
Content-Type: text/html; charset=utf-8

<p>Hello world 😵‍💫</p>`);

console.log(email.subject); // "My awesome email 🤓"
<summary>TypeScript</summary> typescript import PostalMime from './node_modules/postal-mime/src/postal-mime.js'; import type { Email } from 'postal-mime'; const email: Email = await PostalMime.parse(`Subject: My awesome email 🤓 Content-Type: text/html; charset=utf-8 <p>Hello world 😵‍💫</p>`); console.log(email.subject); // "My awesome email 🤓"

Node.js

In Node.js (including serverless functions), import it directly from postal-mime:

import PostalMime from 'postal-mime';
import util from 'node:util';

const email = await PostalMime.parse(`Subject: My awesome email 🤓
Content-Type: text/html; charset=utf-8

<p>Hello world 😵‍💫</p>`);

// Use 'util.inspect' for pretty-printing
console.log(util.inspect(email, false, 22, true));
<summary>TypeScript</summary> typescript import PostalMime from 'postal-mime'; import type { Email, PostalMimeOptions } from 'postal-mime'; import util from 'node:util'; const options: PostalMimeOptions = { attachmentEncoding: 'base64' }; const email: Email = await PostalMime.parse(`Subject: My awesome email 🤓 Content-Type: text/html; charset=utf-8 <p>Hello world 😵‍💫</p>`, options); // Use 'util.inspect' for pretty-printing console.log(util.inspect(email, false, 22, true));

Cloudflare Email Workers

Use the message.raw as the raw email data for parsing:

import PostalMime from 'postal-mime';

export default {
    async email(message, env, ctx) {
        const email = await PostalMime.parse(message.raw);

        console.log('Subject:', email.subject);
        console.log('HTML:', email.html);
        console.log('Text:', email.text);
    }
};
<summary>TypeScript</summary> typescript import PostalMime from 'postal-mime'; import type { Email } from 'postal-mime'; export default { async email(message: ForwardableEmailMessage, env: Env, ctx: ExecutionContext): Promise<void> { const email: Email = await PostalMime.parse(message.raw); console.log('Subject:', email.subject); console.log('HTML:', email.html); console.log('Text:', email.text); } };

TypeScript Support

PostalMime includes comprehensive TypeScript type definitions. All types are exported and can be imported from the main package:

import PostalMime, { addressParser, decodeWords } from 'postal-mime';
import type {
    Email,
    Address,
    Mailbox,
    Header,
    Attachment,
    PostalMimeOptions,
    AddressParserOptions,
    RawEmail
} from 'postal-mime';

[!NOTE] PostalMime is written in JavaScript but provides comprehensive TypeScript type definitions. All types are validated through both compile-time type checking and runtime type validation tests to ensure accuracy.

Available Types

  • Email - The main parsed email object returned by PostalMime.parse()
  • Address - Union type representing either a Mailbox or an address group
  • Mailbox - Individual email address with name and address fields
  • Header - Email header with key and value
  • Attachment - Email attachment with metadata and content
  • PostalMimeOptions - Configuration options for parsing
  • AddressParserOptions - Configuration options for address parsing
  • RawEmail - Union type for all accepted email input formats

Type Narrowing

TypeScript users can use type guards to narrow address types:

import type { Address, Mailbox } from 'postal-mime';

function isMailbox(addr: Address): addr is Mailbox {
    return !('group' in addr) || addr.group === undefined;
}

// Usage
if (email.from && isMailbox(email.from)) {
    console.log(email.from.address); // TypeScript knows this is a Mailbox
}

API

PostalMime.parse()

PostalMime.parse(email, options) -> Promise<Email>
  • email: An RFC822 formatted email. This can be a string, ArrayBuffer/Uint8Array, Blob (browser only), Buffer (Node.js), or a ReadableStream.
  • options: Optional configuration object:
    • rfc822Attachments (boolean, default: false): Treat message/rfc822 attachments without a Content-Disposition as attachments.
    • forceRfc822Attachments (boolean, default: false): Treat all message/rfc822 parts as attachments.
    • attachmentEncoding (string, default: "arraybuffer"): Determines how attachment content is decoded in the parsed email:
      • "base64"
      • "utf8"
      • "arraybuffer" (no decoding, returns ArrayBuffer)
    • maxNestingDepth (number, default: 256): Maximum allowed MIME part nesting depth. Throws an error if exceeded.
    • maxHeadersSize (number, default: 2097152): Maximum allowed total header size in bytes (default 2MB). Throws an error if exceeded.

[!IMPORTANT] The maxNestingDepth and maxHeadersSize options provide built-in security against malicious emails with deeply nested MIME structures or oversized headers that could cause performance issues or memory exhaustion.

Returns: A Promise that resolves to a structured Email object with the following properties:

  • headers: An array of Header objects, each containing:
    • key: Lowercase header name (e.g., "dkim-signature").
    • value: Unprocessed header value as a string.
  • from, sender: Processed Address objects (can be a Mailbox or address group):
    • name: Decoded display name, or an empty string if not set.
    • address: Email address.
    • group: Array of Mailbox objects (only for address groups).
  • deliveredTo, returnPath: Single email addresses as strings.
  • to, cc, bcc, replyTo: Arrays of Address objects (same structure as from).
  • subject: Subject line of the email.
  • messageId, inReplyTo, references: Values from their corresponding headers.
  • date: The email's sending time in ISO 8601 format (or the original string if parsing fails).
  • html: String containing the HTML content of the email.
  • text: String containing the plain text content of the email.
  • attachments: Array of Attachment objects:
    • filename: String or null
    • mimeType: String
    • disposition: "attachment", "inline", or null
    • related: Boolean (optional, true if it's an inline image)
    • contentId: String (optional)
    • content: ArrayBuffer or string, depending on attachmentEncoding
    • encoding: "base64" or "utf8" (optional)
<summary>TypeScript Types</summary> typescript import type { Email, Address, Mailbox, Header, Attachment, PostalMimeOptions, RawEmail } from 'postal-mime'; // Main email parsing const email: Email = await PostalMime.parse(rawEmail); // With options const options: PostalMimeOptions = { attachmentEncoding: 'base64', maxNestingDepth: 100 }; const email: Email = await PostalMime.parse(rawEmail, options); // Working with addresses if (email.from) { // Address can be either a Mailbox or a Group if ('group' in email.from && email.from.group) { // It's a group email.from.group.forEach((member: Mailbox) => { console.log(member.address); }); } else { // It's a mailbox const mailbox = email.from as Mailbox; console.log(mailbox.address); } } // Working with attachments email.attachments.forEach((att: Attachment) => { if (att.encoding === 'base64') { // content is a string const base64Content: string = att.content as string; } else { // content is ArrayBuffer (default) const buffer: ArrayBuffer = att.content as ArrayBuffer; } });

Utility Functions

addressParser()

import { addressParser } from 'postal-mime';

addressParser(addressStr, opts) -> Address[]
  • addressStr: A raw address header string.
  • opts: Optional configuration:
    • flatten (boolean, default: false): If true, ignores address groups and returns a flat array of addresses.

Returns: An array of Address objects, which can be nested if address groups are present.

Example:

import { addressParser } from 'postal-mime';

const addressStr = '=?utf-8?B?44Ko44Od44K544Kr44O844OJ?= <support@example.com>';
console.log(addressParser(addressStr));
// [ { name: 'エポスカード', address: 'support@example.com' } ]
<summary>TypeScript</summary> typescript import { addressParser } from 'postal-mime'; import type { Address, AddressParserOptions } from 'postal-mime'; const addressStr = '=?utf-8?B?44Ko44Od44K544Kr44O844OJ?= <support@example.com>'; const addresses: Address[] = addressParser(addressStr); // With options const options: AddressParserOptions = { flatten: true }; const flatAddresses: Address[] = addressParser(addressStr, options);

decodeWords()

import { decodeWords } from 'postal-mime';

decodeWords(encodedStr) -> string
  • encodedStr: A string that may contain MIME encoded-words.

Returns: A Unicode string with all encoded-words decoded.

Example:

import { decodeWords } from 'postal-mime';

const encodedStr = 'Hello, =?utf-8?B?44Ko44Od44K544Kr44O844OJ?=';
console.log(decodeWords(encodedStr));
// Hello, エポスカード
<summary>TypeScript</summary> typescript import { decodeWords } from 'postal-mime'; const encodedStr = 'Hello, =?utf-8?B?44Ko44Od44K544Kr44O844OJ?='; const decoded: string = decodeWords(encodedStr); console.log(decoded); // Hello, エポスカード

License

© 2021–2025 Andris Reinman

postal-mime is licensed under the MIT No Attribution license.

changelog

Changelog

2.5.0 (2025-10-07)

Features

  • add comprehensive type validation and TypeScript support (81a6467)

2.4.7 (2025-10-07)

Bug Fixes

  • prevent email extraction from quoted strings in addressParser (837d679)

2.4.6 (2025-10-01)

Bug Fixes

  • add security limits for MIME parsing (defbf11)

2.4.5 (2025-09-29)

Bug Fixes

  • handle broken quoted-printable sequences and add prettier formatter (ec3bc64)

2.4.4 (2025-06-26)

Bug Fixes

  • TextDecoder: Fall back to windows-1252 for an unknown charset instead of throwing (d5b917d)

2.4.3 (2025-01-24)

Bug Fixes

  • TextDecoder: Do not reuse text decoders to avoid spilling data from one instance to another (8b1013e)

2.4.2 (2025-01-24)

Bug Fixes

  • decodeWords: Better handling of decoded words (e0f0047)

2.4.1 (2025-01-05)

Bug Fixes

2.4.0 (2025-01-05)

Features

  • attachments: Added new option 'attachmentEncoding' to return attachment content as a string, not arraybuffer (0f7e9df)

2.3.2 (2024-09-23)

Bug Fixes

  • Modified README to trigger a new release (previous npm publish failed) (f975ef4)

2.3.1 (2024-09-23)

Bug Fixes

  • message/rfc822: Added option 'forceRfc822Attachments' to handle all message/rfc822 nodes as attachments instead of inline content (bf47621)

2.3.0 (2024-09-23)

Features

  • Treat message/rfc822 as an attachment for delivery-status and feedback-report (21e6224)

2.2.9 (2024-09-16)

Bug Fixes

  • exports: Define 'default' exports as last for legacy compatibility (a9518c8)

2.2.8 (2024-09-14)

Bug Fixes

  • module: add default to module exports (#56) (4f99ebe)

2.2.7 (2024-07-31)

Bug Fixes

  • rfc822: Only inline message/rfc822 messages if Content-Disposition is (53024de)

2.2.6 (2024-07-09)

Bug Fixes

  • types: Updated type for attachment.content to ArrayBuffer (191524f)

2.2.5 (2024-04-11)

Bug Fixes

  • types: Fixed Address type (57908e4)

2.2.4 (2024-04-11)

Bug Fixes

  • exports: Export addressParser and decodeWords functions (43d3187)

2.2.3 (2024-04-11)

Bug Fixes

  • attachments: Added description key from Content-Description attachment header (6e29de9)
  • calendar-attachments: treat text/calendar as an attachment (2196b49)

2.2.2 (2024-04-10)

Bug Fixes

  • parse: Do not throw on empty input when initializing an array buffer object (ddae5b4)

2.2.1 (2024-03-31)

Bug Fixes

  • parser: Reply-To value must be an array, not a single address object (280bd8d)

2.2.0 (2024-03-26)

Features

  • interface: Added statis parse() method to simplify usage (await PostalMime.parse(email)) (c2faa27)

2.1.2 (2024-02-29)

Bug Fixes

  • git: re-renamed git repo (29d235e)
  • git: Renamed git repository (829e537)

2.1.1 (2024-02-26)

Bug Fixes

  • types: Updated types for PostalMime (bc90f6d)

2.1.0 (2024-02-22)

Features

  • workers: Support Cloudflare Email Workers out of the box (4904708)

Bug Fixes

  • module: add types to module exports (#23) (1ee4a42)

2.0.2 (2023-12-08)

Bug Fixes

  • test: Added a tests runner and some tests (8c6f7fb)
  • test: Added test action (c43c086)

2.0.1 (2023-11-05)

Bug Fixes

  • npm: DO not ignore src folder when publishing to npm (ef8a2df)

2.0.0 (2023-11-03)

⚠ BREAKING CHANGES

  • module: Use as an ES module, do not build with webpack

Features

  • module: Use as an ES module, do not build with webpack (70df152)

1.1.0 (2023-11-02)

Features

  • deploy: automatic publishing (64f9a81)
  • license: changed license from AGPL to MIT-0 (d0ca0dc)

Bug Fixes