mailparser

Maintenance Mode Warning

mailparser is currently in maintenance mode.

• What this means: The module will continue to receive security updates and critical bug fixes.
• What is NOT happening: No new features or feature changes will be added.
• Recommendation: For new projects, consider using PostalMime, which supports both Node.js and browser environments.

After installation, import the mailparser object into your Node.js script using require.

const mailparser = require('mailparser');

Install the mailparser module using npm to add it to your Node.js project.

$ npm install mailparser

The simple parser returns a mail object containing the extracted components of the email. Key properties include:

• attachments: An array of attachment objects. Each attachment includes a content property which is a Buffer.
• text: The plain text body of the email.
• html: The HTML body of the email (if processed).
• textAsHtml: A text version of the email treated as HTML.
• Header-derived properties: The parser automatically promotes common headers to top-level properties:
  • subject
  • references
  • date
  • to
  • from
  • cc
  • bcc
  • message-id
  • in-reply-to
  • reply-to

When instantiating MailParser, you can provide a configuration object to customize parsing behavior:

• Iconv: An optional Iconv implementation (e.g., iconv-lite) to handle character encoding decoding.
• checksumAlgo: The algorithm used to calculate checksums for attachments (defaults to 'md5').
• formatDateString: A function used to format the Date header in the final text output.
• keepDeliveryStatus: If false, message/delivery-status parts are treated as text content rather than separate entities.
• maxHtmlLengthToParse: A limit on the number of bytes of HTML content to be parsed into text. If exceeded, an error is emitted.
• skipHtmlToText: If true, the parser will not attempt to convert HTML parts to text content.

Note: If Iconv is provided, MailParser uses it via an internal IconvDecoder wrapper.

When using the simple parser, you can pass an options object to control parsing behavior.

One notable option is:

• keepCidLinks: A boolean. If true, the parser will not attempt to update image links (CID references) in the HTML body. If false (default), the parser will attempt to transform CID links into base64 data URIs within the mail.html property.

The MailParser class provides utility methods to format address objects (from email headers) into human-readable strings.

getAddressesHTML(value)

Converts an array of address objects into an HTML string. It uses <span> tags for grouping and <a> tags for email addresses.

• Structure: <span class="mp_address_group"><span class="mp_address_name">Name</span> <a href="mailto:email" class="mp_address_email">email</a></span>.

getAddressesText(value)

Converts an array of address objects into a plain text string.

• Structure: "Name" <email> or simply email if no name is present.

The default export of lib/simple-parser.js provides a high-level, asynchronous way to parse email messages. It supports three input types: a string, a Buffer, or a ReadableStream.

Depending on how you call it, the function behaves in two ways:

1. Callback Pattern: Pass (input, options, callback). The callback follows the standard Node.js error-first pattern: callback(err, mail).
2. Promise Pattern: Pass (input, options). If no callback is provided, the function returns a Promise that resolves to the parsed mail object or rejects on error.

If you provide options as a function, it is treated as the callback, and options is set to false.

The MailParser class is a Transform stream that parses incoming email message data. It is designed to be used in a streaming pipeline, where you pipe raw email data into it, and it emits parsed objects (like attachments or text content) through its readable side.

Key characteristics:

• Writable side: Accepts raw binary email data (non-object mode).
• Readable side: Emits parsed objects (object mode), such as attachment objects or the final parsed text/HTML content.
• Events: Emits headers and headerLines when the root message headers are parsed.
• Output: When the stream ends, it pushes the parsed text/HTML content as the final object.

The updateImageLinks(replaceCallback, done) method is used to replace cid: (Content-ID) references in the email's HTML body with actual URLs (e.g., data URIs or hosted URLs).

Workflow:

1. It scans the HTML for cid: patterns.
2. It matches these CIDs against the attachmentList to ensure they are images (image/* content type).
3. For each matched image, it calls the provided replaceCallback.
4. The replaceCallback is expected to take an attachment object and return a URL via a callback: (err, url) => { ... }.
5. Once all replacements are processed, it calls done(err, updatedHtml).

Options affecting this behavior:

• skipImageLinks: If true, the method returns the original HTML without any changes.

The textToHtml(str) method converts a plain text string into an HTML representation. It performs several transformations:

• Linkification: If options.skipTextLinks is not set, it attempts to identify URLs and wrap them in <a> tags.
• HTML Encoding: It encodes special characters using HTML entities to prevent XSS.
• Line Break Handling: It converts double newlines into <p> tags and single newlines into <br/> tags.

Options affecting this behavior:

• skipTextToHtml: If true, the method returns an empty string immediately.
• skipTextLinks: If true, the method skips the automatic detection and wrapping of URLs.

Note: The method uses he.encode with { useNamedReferences: true } for encoding.