Skip to main content

Quick Start

postal-mime mascot carrying emails

This page parses a message and reads the most used properties of the result. It assumes postal-mime is installed.

Parse a message​

PostalMime.parse() takes the raw message and returns a promise of the parsed Email object:

import PostalMime from 'postal-mime';

const email = await PostalMime.parse(`From: Alice <alice@example.com>
To: bob@example.com
Subject: Hello World
Date: Mon, 15 Jan 2024 10:30:00 +0000
Content-Type: text/plain; charset=utf-8

This is the email body.`);

console.log(email.from);    // { address: 'alice@example.com', name: 'Alice' }
console.log(email.to);      // [ { address: 'bob@example.com', name: '' } ]
console.log(email.subject); // "Hello World"
console.log(email.date);    // "2024-01-15T10:30:00.000Z"
console.log(email.text);    // "This is the email body.\n"

The raw message can be a string, an ArrayBuffer, a Uint8Array or Node.js Buffer, a Blob or File, or a ReadableStream. When you read a message from a file or the network, pass the bytes rather than a decoded string, so that text in other charsets is decoded correctly:

import PostalMime from 'postal-mime';
import { readFile } from 'node:fs/promises';

const email = await PostalMime.parse(await readFile('message.eml'));
console.log(email.subject);

What the result holds​

PropertyHolds
from, senderA single address object
to, cc, bcc, replyToArrays of address objects
subjectThe decoded subject
dateThe date as an ISO 8601 string
messageId, inReplyTo, referencesThreading headers
text, htmlThe plain text and HTML bodies
attachmentsEvery part that is not part of the body
headers, headerLinesEvery header, parsed and raw

Properties other than headers, headerLines and attachments are left out when the message has no value for them. The Email Object page documents each one.

Text and HTML​

text and html are filled from the parts the message has. A message with only an HTML part has no text:

import PostalMime from 'postal-mime';

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

<h1>Welcome!</h1>
<p>Thanks for subscribing.</p>`);

console.log(email.html); // "<h1>Welcome!</h1>\n<p>Thanks for subscribing.</p>\n"
console.log(email.text); // undefined

A multipart/alternative message usually carries both. See Text and HTML for how a body made of several parts is assembled.

warning

html is the sender's markup and is not sanitized. Sanitize it or render it in a sandboxed iframe before showing it, see the Security guide.

Attachments​

import PostalMime from 'postal-mime';

const email = await PostalMime.parse(`Subject: Report
Content-Type: multipart/mixed; boundary="b"

--b
Content-Type: text/plain

The report is attached.
--b
Content-Type: text/csv; name="report.csv"
Content-Disposition: attachment; filename="report.csv"

month,total
--b--
`);

for (const attachment of email.attachments) {
    console.log(attachment.filename);           // "report.csv"
    console.log(attachment.mimeType);           // "text/csv"
    console.log(attachment.disposition);        // "attachment"
    console.log(attachment.content.byteLength); // 11
}

content is an ArrayBuffer by default. The attachmentEncoding option returns it as a base64 or UTF-8 string instead.

TypeScript​

import PostalMime from 'postal-mime';
import type { Email } from 'postal-mime';

const email: Email = await PostalMime.parse('Subject: Hello\n\nHi there');
const subject: string = email.subject ?? '(no subject)';
console.log(subject);

See Also​