PostalMime

PostalMime is an email parsing library that runs in Node.js, browsers (including Web Workers), and serverless environments like Cloudflare Email Workers. It takes a raw RFC822/MIME email message and turns it into a structured JavaScript object with headers, recipients, body text/HTML, and attachments.

Built by the makers of EmailEngine (a self-hosted IMAP/SMTP gateway), it ships with zero runtime dependencies, full TypeScript typings, and built-in safety limits against deeply nested MIME structures and oversized headers — making it a practical choice anywhere raw email needs to be parsed reliably, including in resource-constrained edge/serverless runtimes.

What You Get

• PostalMime.parse() — parses a raw RFC822/MIME message into structured JSON (headers, addresses, body, attachments)
• Zero runtime dependencies, keeping bundle size and supply-chain surface minimal for edge/serverless deployment
• Full TypeScript type definitions shipped alongside the package
• Built-in decoders for base64, quoted-printable, and HTML entities plus an RFC-compliant address parser
• Safety limits against maliciously deep MIME nesting and oversized headers to guard against denial-of-service payloads

Common Use Cases

• Parsing inbound email in a Cloudflare Email Worker or other serverless email-routing pipeline
• Building a webmail client or email-processing tool that needs structured access to headers and attachments in the browser
• Extracting attachments and body content from raw email payloads received via IMAP/SMTP gateways like EmailEngine
• Running email parsing inside a Web Worker to keep MIME decoding off the browser’s main thread

Under The Hood

Architecture: The core src/postal-mime.js module drives a streaming-style MIME tree walk, delegating structural parsing to mime-node.js (which models the recursive multipart/nested-part structure of a MIME message) and decoding to dedicated single-purpose modules — base64-decoder.js/base64-encoder.js, qp-decoder.js (quoted-printable), pass-through-decoder.js, and decode-strings.js/html-entities.js for text normalization — with address-parser.js handling RFC 5322 address-header parsing independently. This modular decoder-per-encoding design lets the library run unmodified across Node.js, browsers, and Workers runtimes since none of the modules depend on Node-specific APIs. Tech Stack: Zero runtime dependencies is a headline design constraint — the entire ~4,500-line src/ implementation is hand-written rather than composed from existing MIME libraries, published as native ESM (type: module) with a build script (scripts/build-cjs.js) generating a CommonJS dist/postal-mime.cjs for compatibility, and full TypeScript declarations (postal-mime.d.ts) hand-maintained alongside the JS source. Code Quality: The test suite (~8,500 lines) is roughly double the size of the implementation, using Node’s built-in node --test runner plus ESLint and tsc --noEmit type-checking wired into the npm test script — a strong ratio suggesting thorough edge-case coverage for a parser that has to handle adversarial or malformed email input safely. API Design: The single async PostalMime.parse() entry point is deliberately minimal — one call in, one structured object out — with utility exports (addressParser(), decodeWords()) available separately for callers who only need a sub-piece of the parsing logic, keeping the common case a one-liner while still exposing internals for advanced use.