Parse Emails in Browser & Serverless: postal-mime

postal-mime is a JavaScript library that parses RFC822 email messages directly in browsers and serverless environments.

It transforms raw email data into structured JavaScript objects containing headers, recipients, attachments, message content, and more.

More Features:

• Can be run in Web Workers to avoid blocking the main thread.
• Runs in serverless platforms like Cloudflare Email Workers.
• Handles binary data like attachments using ArrayBuffers.
• Decodes various formats, including Base64, Quoted-Printable, MIME Encoded Words, and even parameter value continuations for attachment filenames (e.g., emojis).
• Supports proper charset handling for all supported transfer encodings.
• Accepts email input as a String, ArrayBuffer, or File input element.

Installation:

# NPM
$ npm install postal-mime

How to use it:

1. Import postal-mime and use the parse() function to process a raw RFC822 formatted email message.

// Browser
import PostalMime from './node_modules/postal-mime/src/postal-mime.js';
const email = await PostalMime.parse(`From: someone@example.com
To: someone_else@example.com
Subject: An RFC 822 formatted message`);
// "An RFC 822 formatted message"
console.log(email.subject);

// Node.js
import PostalMime from 'postal-mime';
import util from 'node:util';
const email = await PostalMime.parse(`From: someone@example.com
To: someone_else@example.com
Subject: An RFC 822 formatted message`);
// Use 'util.inspect' for pretty-printing
console.log(util.inspect(email, false, 22, true));

// Cloudflare Email Workers
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);
  }
};

2. The PostalMime.parse() function accepts an optional second argument for configuration:

• rfc822Attachments (boolean, default: false): If true, message/rfc822 attachments without a Content-Disposition header are treated as attachments.
• forceRfc822Attachments (boolean, default: false): If true, all message/rfc822 parts are treated as attachments.
• attachmentEncoding (string, default: “arraybuffer”): Controls how attachment content is returned: “base64”: Returns the content as a Base64 encoded string; “utf8”: Returns the content as a UTF-8 encoded string; “arraybuffer”: Returns the content as an ArrayBuffer (no decoding).

PostalMime.parse(email, {
  rfc822Attachments: false,
  forceRfc822Attachments: false,
  attachmentEncoding: "arraybuffer"
}

3. The PostalMime.parse() function returns a Promise. This Promise resolves to a structured object containing the parsed email data.

• headers: An array of header objects. Each object has a key (lowercase header name, e.g., “subject”) and a value (the raw header value).
• from, sender: Address objects. These contain a name (the display name, if present) and an address (the email address).
• deliveredTo, returnPath: Single email addresses as strings.
• to, cc, bcc, replyTo: Arrays of address objects (same format as from and sender).
• subject: The subject line of the email.
• messageId, inReplyTo, references: Values from the corresponding headers.
• date: The email’s date. If parsing is successful, this is in ISO 8601 format. If parsing fails, it’s the original date string.
• html: The HTML content of the email (if present).
• text: The plain text content of the email (if present).
• attachments: An array of attachment objects. Each object contains:
  • filename: The filename of the attachment.
  • mimeType: The MIME type of the attachment.
  • disposition: “attachment”, “inline”, or null.
  • related: true if the attachment is an inline image (related to the HTML content).
  • contentId: The Content-ID of the attachment.
  • content: The attachment content (either an ArrayBuffer or a string, based on attachmentEncoding).
  • encoding: The encoding used for the attachment (e.g., “base64”).

4. Helpful utilities for email processing:

// Parse email addresses with optional name components
import { addressParser} from 'postal-mime';
const addresses = addressParser('=?utf-8?B?44Ko44Od44K544Kr44O844OJ?= <support@cssscript.com>');

// Decode MIME encoded words
import { decodeWords } from 'postal-mime';
const encodedStr = 'Hello, =?utf-8?B?44Ko44Od44K544Kr44O844OJ?=';
console.log(decodeWords(encodedStr));

Changelog:

10/24/2025

• v2.6.0

10/07/2025

• add comprehensive type validation and TypeScript support

10/07/2025

• prevent email extraction from quoted strings in addressParser

10/02/2025

• add security limits for MIME parsing

The post Parse Emails in Browser & Serverless: postal-mime appeared first on CSS Script.