postal-mime

postal-mime

Email parser for browser environments.

PostalMime can be run in the main web thread or from Web Workers.

Source

Source code is available from Github.

Demo

See this example.

Usage

First install the module from npm:

$ npm install postal-mime

next import the PostalMime class into your script:

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

or when using from a Node.js app

import PostalMime from 'postal-mime';

Promises

All postal-mime methods use Promises, so you need to wait using await or wait for the then() method to fire until you get the response.

Browser

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

const parser = new PostalMime();
const email = await parser.parse(`Subject: My awesome email 🤓
Content-Type: text/html; charset=utf-8

<p>Hello world 😵‍💫</p>`);

console.log(email.subject);

Node.js

It is pretty much the same as in the browser.

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

const parser = new PostalMime();
const email = await parser.parse(`Subject: My awesome email 🤓
Content-Type: text/html; charset=utf-8

<p>Hello world 😵‍💫</p>`);

console.log(util.inspect(email, false, 22, true));

Cloudflare Email Workers

Pretty much the same as in Node.js. Use message.raw as the raw message for parsing.

import PostalMime from 'postal-mime';

export default {
    async email(message, env, ctx) {
        const parser = new PostalMime();
        const email = await parser.parse(message.raw);

        console.log('Subject: ', email.subject);
        console.log('HTML: ', email.html);
        console.log('Text: ', email.text);
    }
};

parser.parse()

parser.parse(email) -> Promise

Where

• email is the rfc822 formatted email. Either a string, an ArrayBuffer, a Blob object or a Node.js Buffer

NB you can call parse() only once. If you need to parse another message, create a new PostalMime object.

This method parses an email message into a structured object with the following properties:

• headers is an array of headers in the same order as found from the message (topmost headers first).
  • headers[].key is lowercase key of the header line, eg. "dkim-signature"
  • headers[].value is the unprocessed value of the header line
• from, sender, replyTo includes a processed object for the corresponding headers
  • from.name is decoded name (empty string if not set)
  • from.address is the email address
• deliveredTo, returnPath is the email address from the corresponding header
• to, cc, bcc includes an array of processed objects for the corresponding headers
  • to[].name is decoded name (empty string if not set)
  • to[].address is the email address
• subject is the email subject line
• messageId, inReplyTo, references includes the value as found from the corresponding header without any processing
• date is the email sending time formatted as an ISO date string (unless parsing failed and in this case the original value is used)
• html is the HTML content of the message as a string
• text is the plaintext content of the message as a string
• attachments is an array that includes message attachments
  • attachment[].filename is the file name if provided
  • attachment[].mimeType is the MIME type of the attachment
  • attachment[].disposition is either "attachment", "inline" or null if disposition was not provided
  • attachment[].related is a boolean value that indicats if this attachment should be treated as embedded image
  • attachment[].contentId is the ID from Content-ID header
  • attachment[].content is an ArrayBuffer that contains the attachment file

License

© 2021-2023 Andris Reinman

postal-mime is licensed under the MIT No Attribution license

Changelog

2.1.1 (2024-02-26)

Bug Fixes

• types: Updated types for PostalMime (bc90f6d)