tessl/npm-mailparser

Advanced email parser for Node.js that handles email parsing as a stream for memory-efficient processing of large messages

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Mailparser

Name: tessl/npm-mailparser
Author: tessl

Mailparser is an advanced email parser for Node.js that handles email parsing as a stream, making it capable of processing very large messages (100MB+) with relatively low overhead. It provides comprehensive email parsing capabilities including header extraction, body parsing, attachment handling, and support for various email encodings and formats.

Package Information

Package Name: mailparser
Package Type: npm
Language: JavaScript
Installation: npm install mailparser

Core Imports

const { MailParser, simpleParser } = require('mailparser');

For ES modules:

import { MailParser, simpleParser } from 'mailparser';

Basic Usage

const { simpleParser } = require('mailparser');
const fs = require('fs');

// Parse email from file
simpleParser(fs.createReadStream('email.eml'))
  .then(mail => {
    console.log(mail.subject);
    console.log(mail.text);
    console.log(mail.attachments.length);
  })
  .catch(err => {
    console.error(err);
  });

// Parse email from string
const emailString = 'From: sender@example.com...';
simpleParser(emailString)
  .then(mail => {
    console.log(mail.from.text);
    console.log(mail.html);
  });

Architecture

Mailparser is built around two main components:

Simple Parser: simpleParser function for one-shot parsing with automatic attachment handling
Streaming Parser: MailParser class for advanced streaming scenarios with event-based processing
Stream Processing: Memory-efficient parsing using Node.js streams for large email handling
Character Encoding: Comprehensive support for various character encodings including Japanese encodings
Attachment Handling: Stream-based attachment processing with checksums and metadata

Capabilities

Simple Email Parsing

High-level email parsing function that handles the complete parsing process and returns a structured mail object with all content and attachments.

function simpleParser(
  input: string | Buffer | Stream,
  options?: ParseOptions,
  callback?: (err: Error | null, mail: ParsedMail) => void
): Promise<ParsedMail>;

interface ParseOptions {
  keepCidLinks?: boolean;
  skipHtmlToText?: boolean;
  skipImageLinks?: boolean;
  skipTextToHtml?: boolean;
  skipTextLinks?: boolean;
  keepDeliveryStatus?: boolean;
  Iconv?: any;
  checksumAlgo?: string;
  maxHtmlLengthToParse?: number;
  formatDateString?: (date: Date) => string;
}

interface ParsedMail {
  headers: Map<string, any>;
  headerLines: HeaderLine[];
  html?: string;
  text?: string;
  textAsHtml?: string;
  subject?: string;
  date?: Date;
  from?: AddressObject;
  to?: AddressObject;
  cc?: AddressObject;
  bcc?: AddressObject;
  messageId?: string;
  inReplyTo?: string;
  replyTo?: AddressObject;
  references?: string[];
  attachments: Attachment[];
}

Simple Email Parsing

Streaming Email Parsing

Low-level streaming parser class for advanced email processing scenarios where you need fine-grained control over the parsing process and event handling.

class MailParser extends Transform {
  constructor(options?: ParseOptions);
  
  // Event listeners for Transform stream
  on(event: 'headers', listener: (headers: Map<string, any>) => void): this;
  on(event: 'readable', listener: () => void): this;
  on(event: 'end', listener: () => void): this;
  on(event: 'error', listener: (err: Error) => void): this;
  
  // Stream reading method
  read(): TextData | AttachmentData | null;
}

interface TextData {
  type: 'text';
  html?: string;
  text?: string;
  textAsHtml?: string;
}

interface AttachmentData {
  type: 'attachment';
  content: Stream;
  contentType: string;
  filename?: string;
  contentDisposition?: string;
  contentId?: string;
  headers: Map<string, any>;
  checksum?: string;
  size?: number;
  release(): void;
}

Streaming Email Parsing

Types

interface HeaderLine {
  key: string;
  line: string;
}

interface AddressObject {
  value: Address[];
  html: string;
  text: string;
}

interface Address {
  name?: string;
  address: string;
  group?: Address[];
}

interface Attachment {
  type: 'attachment';
  content: Buffer;
  contentType: string;
  partId?: string;
  contentDisposition?: string;
  filename?: string;
  contentId?: string;
  cid?: string;
  related?: boolean;
  headers: Map<string, any>;
  checksum?: string;
  size?: number;
}