postal-mime

In Node.js or serverless environments, you can import PostalMime directly from the package name. You can also pass a PostalMimeOptions object to configure parsing behavior, such as attachment encoding.

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

const options = {
    attachmentEncoding: 'base64'
};

const email = await PostalMime.parse(rawEmailData, options);

// Use 'util.inspect' for pretty-printing the result
console.log(util.inspect(email, false, 22, true));

For projects using CommonJS, postal-mime provides a compatible build that allows you to use require() for both the main class and utility functions.

const PostalMime = require('postal-mime');
const { addressParser, decodeWords } = require('postal-mime');

const email = await PostalMime.parse(rawEmailData);

When using the library in a browser environment (including Web Workers), you should import the module directly from the src directory to ensure compatibility with browser-native ESM.

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

const email = await PostalMime.parse(rawEmailData);

To use postal-mime in your project, install it using npm:

npm install postal-mime

In Cloudflare Email Workers, you can parse the incoming email by passing message.raw to PostalMime.parse().

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);
    }
};

Since Address is a union type (representing either a Mailbox or an address group), you can use type guards to safely access properties like address on a Mailbox.

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
}

The addressParser() utility converts a raw address header string into an array of Address objects. If the header contains address groups, the returned array will be nested.

Options

• flatten (boolean, default: false): If set to true, the parser ignores address groups and returns a flat array of addresses.

import { addressParser } from 'postal-mime';

const addressStr = '=?utf-8?B?44Ko44Od44K544Kr44O844OJ?= <support@example.com>';
console.log(addressParser(addressStr));
// [ { name: 'エポスカード', address: 'support@example.com' } ]

The decodeWords() function takes a string that may contain MIME encoded-words (e.g., =?utf-8?B?...?=) and returns a Unicode string with all encoded-words decoded.

import { decodeWords } from 'postal-mime';

const encodedStr = 'Hello, =?utf-8?B?44Ko44Od44K544Kr44O844OJ?=';
console.log(decodeWords(encodedStr));
// Hello, エポスカード

The core functionality of postal-mime is the PostalMime.parse() method. It accepts a raw email message (RFC822 format) and returns a structured Email object containing headers, recipients, attachments, and body content (HTML/Text).

import PostalMime from 'postal-mime';

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 🤓"

When instantiating PostalMime via the constructor, you can provide an options object to control parsing behavior:

• maxNestingDepth: Maximum depth for MIME tree nesting (default: 256).
• maxHeadersSize: Maximum size in bytes for headers (default: 2097152 / 2MB).
• attachmentEncoding: Determines how attachment content is returned. Supported values are 'arraybuffer' (default), 'base64', and 'utf8'.
• rfc822Attachments: Boolean determining if message/rfc822 parts are treated as inline messages or attachments.
• forceRfc822Attachments: Boolean to force message/rfc822 parts to be treated as attachments (useful for certain report emails).

Note: attachmentEncoding is case-insensitive and ignores hyphens, underscores, and spaces.

const parser = new PostalMime({
  attachmentEncoding: 'base64',
  maxNestingDepth: 128
});