Mailparser

adminMarch 20, 2023

0 39 4 minutes read

How to create an email parser in node.js

YOU ARE READING: Mailparser AT Vccidata_En

Advanced email parser for Node.js. Everything is handled as a stream, so it should be able to parse even very large messages (100MB+) with relatively little overhead.

The module provides two separate modes, a MailParser lower-level class and simpleParser function. The latter is easier to use (hence the name) but less resource efficient as it buffers the contents of attachments in memory.

Reading: How to create an email parser in node.js

Install

simpleParser

simpleParser is the easiest way to parse emails. You only need to provide a message source to get a parsed email structure in return. As an added bonus, any embedded images in HTML (e.g. the images referencing attachments with cid: URIs) are replaced with base64 encoded data URIs, allowing the message to be displayed without any additional processing. However, note that this module does not do any security cleaning (e.g. removing javascript etc.), this is left to your own application.

See MailParser Options List

or like a Promise:

or even with async..await:

Where

source is either a stream, a buffer or a string , which must be parsed
options is an optional options object
err is the possible error object
Mail is a structured email object

Mail object

Has parsed Mail* object the following properties

headers – a map object with header keys in lowercase
subject is the subject line (also available from header mail.headers.get(‘subject’))
from is an address object for header From:
to is an address object for the To: header
cc is an address object for the Cc: header
bcc is an address object for the Bcc: header (normally absent)
date is a Date object for the Date: header
messageId is the Message ID value string
inReplyTo is the In-Reply-To value string
reply-to is an address object for the Cc: header
references is an array of referenced message ID values
html is the HTML body of the message. If the message contains embedded images as cid: URLs, these are all replaced with base64-formatted data: URIs
text is the plaintext body of the message
textAsHtml is the plain text body of the message formatted as HTML
attachments is an array of attachments

address object

Address objects have the following structure:

Value an array of address details
- Name is the name part of the email/group
- address is the email address
- group is an array of grouped addresses
See also: How to create a QR code and direct people to a website, document, or other media

text is a formatted address string for plain text context
html is a formatted address string for HTML context

Example

headers Map

headers is e A map with lowercase header keys. So if you want to search for the Subject: header, you can do it like this:

The format of a header depends on the specific key. For most header keys, the value is either a string (a single header) or an array of strings (multiple headers with the same key were found).

Special header keys are the following:

All address headers are converted into address objects

from
an
cc
bcc
Sender
Reply to
Delivered to
return-path

All the different priority headers are converted to priority with the following values:

‘high’
‘normal’
‘low’

references is a string if there is only a single reference ID, or an array if there are multiple IDs
Date value is a date object
The following headers are decomposed into structured objects, where the property value the main value as a string e and the params property contains an object with an additional argument nts as key-value pairs

Content-Type
Content-Disposition
dkim-signature

Some headers are also automatically mime-word- decodes

all address headers (name parts and Punycode-encoded domains are converted to Unicode)
Subject is converted to Unicode

Attachment Object

Attachment objects have the following structure:

filename (if available) filename of the attachment
contentType MIME type of the message
contentDisposition Content disposition type for the attachment, most likely “attachment”
Checksum an MD5 hash of the message content
Size Message size in bytes
Header an M ap value containing the MIME header for the attachment node
content a buffer containing the content of the attachment
contentId the header value of ‘Content-ID’ (if any)
cid contentId without
related if true, then this attachment should not be offered for download (at least not in the main list of attachments)

MailParser

MailParser is a child email parser class. It is a conversion stream that takes the email source as a byte stream for input and outputs data objects for attachments and text content.

Options

skipHtmlToText boolean Do not generate plain text from HTML. Undefined (false) by default.
maxHtmlLengthToParse number The maximum amount of HTML to parse, in bytes. Undefined (infinity) by default.
formatDateString function Provides a custom formatting function. Undefined by default.
skipImageLinks boolean Skip converting CID attachments to data URL images. Undefined (false) by default.
skipTextToHtml boolean Do not generate HTML from a plain text message. Undefined by default (false).
skipTextLinks boolean Skip links in plain text content. Undefined by default (false).
Iconv object Iconv-lite by default
keepCidLinks simpleParser-only boolean option. Sets skipImageLinks to true.

Event “headers”

The parser emits “headers” once message headers have been processed. The header object is a map. Different header keys have different types of values, for example address headers have the address object/array as value while the subject value is a string.

Header keys in the map are lowercase.

Event ‘data’

Event ‘data’ or ‘readable’ outputs message content objects. The type of the object can be determined by the type property. There are currently two types of data objects

‘attachment’ indicates that this object is an attachment
‘text’ indicates that this object contains the HTML and text parts that contains message. This object is output once and contains both values

Attachment object

Attachment object is the same as in simpleParser, except that the content is not a buffer but a stream . Additionally, there is a release() method that needs to be called once you’ve processed the attachment. The related property is set after message processing is complete, so this value is not yet available at the data event.

If you do not call release(), then message processing is halted.

Text object

Text object has the following keys:

Text contains the plain text version of the message . Set if the message has at least one ‘text/plain’ node
html contains the HTML version of the message.Set if the message has at least one ‘text/html’ node
textAsHtml contains the plain text version of the message in HTML format. Set if the message has at least one ‘text/plain’ node.

Issues

Charset decoding is handled with iconv-lite, except for ISO- 2022-JP and EUCJP processed by encoding-japanese. Alternatively, you can use the node-iconv module for all character set decoding instead. This module is not included in the Mailparser package, you would need to provide it to Mailparser or simpleParser as a configuration option.