postal-mime vs mailparser
Both turn a raw MIME message into an object you can use, and both are maintained by the same person — Andris Reinman, who also writes Nodemailer. The choice is not about quality. It is about where your code runs and how much of the message you need, and there is a step after either one that neither library takes for you.
The difference in one table
| postal-mime | mailparser | |
|---|---|---|
| Runs in | Node, browsers, Cloudflare Workers | Node only (needs streams + Buffer) |
| API | One call: parse(buffer) → object | simpleParser() for the whole message, or a streaming parser |
| Output | subject, addresses, text, html, attachments | The same, plus decoded headers as a Map, references/in-reply-to, and generated HTML for text-only mail |
| Attachments | ArrayBuffer — fine to forward or upload | Buffer, streaming-friendly for large files |
| Weight | Small, zero-dependency | Pulls in libmime and an encoding library |
| Downloads / month | ~74M | ~33M |
postal-mime
The one you reach for when the code has to run anywhere — an edge function, a Cloudflare Email Worker, a browser-side preview. One function, one object, no streams to wire up.
import PostalMime from "postal-mime";
// postal-mime takes the raw message and returns a plain object.
// Runs in Node, browsers, and edge runtimes — same code everywhere.
const email = await PostalMime.parse(rawMime);
email.subject; // string | undefined
email.from; // { name, address }
email.to; // [{ name, address }]
email.text; // decoded text part
email.html; // decoded HTML part
email.attachments; // [{ filename, mimeType, content: ArrayBuffer }] mailparser
The one you reach for when the message is large, or when you need the parts mailparser exposes beyond the basics: the full header set, threading headers, and a text-to-HTML rendering.
import { simpleParser } from "mailparser";
// mailparser is Node-only and stream-based: simpleParser gives you the whole
// message once, and the stream API lets you walk parts as they arrive.
const email = await simpleParser(rawMime);
email.subject; // string | undefined
email.from; // address object
email.text; // decoded text
email.html; // decoded HTML
email.attachments; // [{ filename, contentType, content: Buffer }]
email.headers; // a Map of every header
email.references; // parsed References / inReplyTo
email.textAsHtml; // generated HTML when the message was text-only Both assume you already have the bytes
That is the catch. Both take a parsed-or-raw message as input. Neither
listens on port 25, terminates TLS, checks SPF/DKIM/DMARC, or tells your
application that mail arrived. In a Worker you have a
message.raw stream because the platform already accepted the mail:
export default {
async email(message, env, ctx) {
// Cloudflare Email Workers hand you a ReadableStream.
const raw = await new Response(message.raw).arrayBuffer();
const parsed = await new PostalMime().parse(raw);
await fetch(env.WEBHOOK_URL, {
method: "POST",
body: JSON.stringify({ subject: parsed.subject, text: parsed.text }),
});
},
}; Outside a platform like that, the usual answer is an SMTP server you operate, or a provider that accepts the mail and delivers it to you.
If the provider parses it first
An inbound email API does the SMTP and MIME work, then POSTs a parsed payload:
{
"id": "msg_4f3c1a9e2b7d48e1a05c6f8b3d2e7a91",
"type": "email.received",
"from": { "address": "ada@example.com", "name": "Ada Lovelace" },
"to": [{ "address": "support@myapp.ai", "name": "Support" }],
"subject": "Re: invoice #1042",
"text": "Looks good — approved!",
"html": "<p>Looks good — approved!</p>",
"textFromHtml": null,
"threadId": "<a1b2c3@mail.example.com>",
"receivedAt": 1785196800000,
"receivedAtIso": "2026-07-28T00:00:00.000Z",
"auth": {
"spf": "pass", "dkim": "pass", "dmarc": "pass",
"spam": "ham", "spamScore": 0.05, "spamSignals": []
},
"attachments": [
{
"id": "msg_4f3c1a9e2b7d48e1a05c6f8b3d2e7a91:0",
"filename": "po.pdf",
"contentType": "application/pdf",
"size": 18213,
"contentId": null,
"disposition": "attachment",
"url": "https://api.mailkite.dev/att/4f3c1a9e2b7d48e1a05c6f8b3d2e7a91/0?exp=…&sig=…",
"content": null
}
]
}
Use that and you can skip the parser entirely for the common case — subject,
text, html and attachment metadata are already there. Reach for
postal-mime or mailparser only when you need the raw
message: re-sending it, rendering it exactly, or running your own heuristics.
MailKite keeps the original bytes retrievable for that.
Which to pick
- Edge, browser, or Workers →
postal-mime. - Node, large attachments, full headers →
mailparser. - You just need subject/text/html → neither, if your inbound provider already parses it.
Want the parsed payload without running a parser? Receive email as JSON — one MX record, signed webhooks, attachments as links.