Simple Email Parsing

/**
 * Parse email data into a structured mail object
 * @param input - Email data as string, Buffer, or readable stream
 * @param options - Optional parsing configuration
 * @param callback - Optional callback function (if not provided, returns Promise)
 * @returns Promise resolving to parsed mail object
 */
function simpleParser(
  input: string | Buffer | Stream,
  options?: ParseOptions,
  callback?: (err: Error | null, mail: ParsedMail) => void
): Promise<ParsedMail>;

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

// Parse from file stream
const mail = await simpleParser(fs.createReadStream('message.eml'));
console.log(mail.subject);
console.log(mail.from.text);
console.log(mail.attachments.length);

// Parse from string with options
const emailString = `From: sender@example.com
To: recipient@example.com
Subject: Test Message

Hello World!`;

const mail = await simpleParser(emailString, {
  skipHtmlToText: true,
  keepCidLinks: true
});

// Parse with callback style
simpleParser(emailBuffer, (err, mail) => {
  if (err) {
    console.error('Parse error:', err);
    return;
  }
  console.log('Subject:', mail.subject);
  console.log('Text:', mail.text);
});

interface ParseOptions {
  /** Keep CID links in HTML instead of converting to base64 data URLs */
  keepCidLinks?: boolean;
  /** Skip converting HTML content to plain text */
  skipHtmlToText?: boolean;
  /** Skip processing image src attributes */
  skipImageLinks?: boolean;
  /** Skip converting plain text to HTML */
  skipTextToHtml?: boolean;
  /** Skip auto-linking URLs in plain text */
  skipTextLinks?: boolean;
  /** Keep message/delivery-status parts as text instead of ignoring */
  keepDeliveryStatus?: boolean;
  /** Custom Iconv instance for character encoding */
  Iconv?: any;
  /** Algorithm for calculating attachment checksums (default: 'md5') */
  checksumAlgo?: string;
  /** Maximum HTML content length to parse (prevents memory issues) */
  maxHtmlLengthToParse?: number;
  /** Custom function for formatting date strings */
  formatDateString?: (date: Date) => string;
}

interface ParsedMail {
  /** Map of all email headers (case-insensitive keys) */
  headers: Map<string, any>;
  /** Array of raw header lines as received */
  headerLines: HeaderLine[];
  /** HTML content of the email */
  html?: string;
  /** Plain text content of the email */
  text?: string;
  /** Plain text converted to HTML format */
  textAsHtml?: string;
  /** Email subject line */
  subject?: string;
  /** Parsed date from Date header */
  date?: Date;
  /** Parsed From addresses */
  from?: AddressObject;
  /** Parsed To addresses */
  to?: AddressObject;
  /** Parsed CC addresses */
  cc?: AddressObject;
  /** Parsed BCC addresses */
  bcc?: AddressObject;
  /** Message-ID header value */
  messageId?: string;
  /** In-Reply-To header value */
  inReplyTo?: string;
  /** Reply-To addresses */
  replyTo?: AddressObject;
  /** References header values as array */
  references?: string[];
  /** Array of all attachments found in the email */
  attachments: Attachment[];
}

// The function throws TypeError for invalid input
try {
  await simpleParser(null); // Throws TypeError
} catch (err) {
  console.error(err.message); // "Input cannot be null or undefined."
}

// Parse errors are returned/thrown normally
try {
  const mail = await simpleParser(corruptedEmailData);
} catch (err) {
  console.error('Failed to parse email:', err);
}

// String input
await simpleParser('From: test@example.com\n\nHello');

// Buffer input  
const buffer = Buffer.from(emailString, 'utf8');
await simpleParser(buffer);

// Stream input
const stream = fs.createReadStream('email.eml');
await simpleParser(stream);