@bernierllc/email-parser

Email parsing utilities for extracting headers, attachments, and content from email messages.

Installation

npm install @bernierllc/email-parser

Quick Start

import { parseEmail } from '@bernierllc/email-parser';

const emailContent = `From: [email protected]
To: [email protected]
Subject: Test Email
Date: Mon, 1 Jan 2025 10:00:00 +0000
Content-Type: text/plain

This is a test email.`;

const result = await parseEmail(emailContent, {
  extractAttachments: true,
  sanitizeContent: true,
  validateAddresses: true
});

if (result.valid && result.email) {
  console.log('Subject:', result.email.subject);
  console.log('From:', result.email.envelope.from);
  console.log('Content:', result.email.content.text);
  console.log('Attachments:', result.email.attachments.length);
}

Features

• Header Parsing: Extract and normalize email headers
• Content Extraction: Parse HTML and plain text content
• Attachment Handling: Extract and process email attachments
• Address Parsing: Parse and validate email addresses
• Encoding Support: Handle various character encodings
• Security: Sanitize content and validate attachments
• Multipart Support: Handle multipart/mixed emails

API Reference

parseEmail(raw, options?)

Parse raw email content into structured data.

Parameters

• raw (string | Buffer) - Raw email content
• options (ParseOptions) - Parsing options

Options

interface ParseOptions {
  extractAttachments?: boolean;     // Default: true
  sanitizeContent?: boolean;        // Default: false
  validateAddresses?: boolean;      // Default: false
  maxAttachmentSize?: number;       // Default: unlimited
  allowedContentTypes?: string[];   // Default: all types
  decodeHeaders?: boolean;          // Default: true
}

Returns

interface ParseResult {
  email?: ParsedEmail;
  valid: boolean;
  errors: ParseError[];
  warnings: ParseWarning[];
  metadata: {
    processingTime: number;
    parsedComponents: string[];
  };
}

Address Parsing

import { parseEmailAddresses, isValidEmailAddress } from '@bernierllc/email-parser';

// Parse address list
const addresses = parseEmailAddresses('[email protected], "John Doe" <[email protected]>');
console.log(addresses);
// [
//   { address: '[email protected]' },
//   { address: '[email protected]', name: 'John Doe' }
// ]

// Validate single address
const isValid = isValidEmailAddress('[email protected]');
console.log(isValid); // true

Content Sanitization

import { sanitizeHtml, sanitizeText } from '@bernierllc/email-parser';

// Sanitize HTML content
const cleanHtml = sanitizeHtml('<script>alert("xss")</script><p>Safe content</p>');
console.log(cleanHtml); // '<p>Safe content</p>'

// Sanitize text content
const cleanText = sanitizeText('Some\r\n\r\ntext\0with\nnull\ncharacters');
console.log(cleanText); // 'Some\n\ntext with null characters'

Types

ParsedEmail

interface ParsedEmail {
  envelope: {
    from: string;
    to: string[];
    cc?: string[];
    bcc?: string[];
  };
  headers: Record<string, string | string[]>;
  subject?: string;
  messageId?: string;
  date?: Date;
  content: {
    text?: string;
    html?: string;
    raw?: string;
  };
  attachments: EmailAttachment[];
  metadata: {
    provider?: string;
    receivedAt: Date;
    size: number;
    hasAttachments: boolean;
    isMultipart: boolean;
    encoding?: string;
  };
}

EmailAttachment

interface EmailAttachment {
  filename?: string;
  contentType: string;
  contentId?: string;
  size: number;
  content: Buffer;
  inline: boolean;
  metadata: {
    encoding?: string;
    checksum?: string;
  };
}

Usage Examples

Basic Email Parsing

const result = await parseEmail(emailContent);

if (result.valid && result.email) {
  // Access email components
  console.log('From:', result.email.envelope.from);
  console.log('To:', result.email.envelope.to);
  console.log('Subject:', result.email.subject);
  console.log('Date:', result.email.date);
  
  // Access content
  if (result.email.content.html) {
    console.log('HTML content available');
  }
  if (result.email.content.text) {
    console.log('Text content available');
  }
}

Multipart Email with Attachments

const result = await parseEmail(multipartEmail, {
  extractAttachments: true,
  maxAttachmentSize: 5 * 1024 * 1024, // 5MB limit
  allowedContentTypes: ['image/*', 'application/pdf']
});

if (result.valid && result.email) {
  // Process attachments
  for (const attachment of result.email.attachments) {
    console.log(`Attachment: ${attachment.filename}`);
    console.log(`Type: ${attachment.contentType}`);
    console.log(`Size: ${attachment.size} bytes`);
    
    // Save attachment
    if (attachment.filename) {
      await fs.writeFile(attachment.filename, attachment.content);
    }
  }
}

Security-Focused Parsing

const result = await parseEmail(emailContent, {
  sanitizeContent: true,
  validateAddresses: true,
  extractAttachments: true,
  maxAttachmentSize: 1024 * 1024, // 1MB limit
  allowedContentTypes: ['text/*', 'image/*']
});

// Check for warnings and errors
if (result.warnings.length > 0) {
  console.log('Warnings:', result.warnings);
}

if (result.errors.length > 0) {
  console.log('Errors:', result.errors);
}

// Sanitized content is safe to display
if (result.valid && result.email) {
  const safeHtml = result.email.content.html; // XSS protection applied
}

Error Handling

The parser provides detailed error and warning information:

const result = await parseEmail(malformedEmail);

if (!result.valid) {
  console.log('Parsing failed:');
  result.errors.forEach(error => {
    console.log(`${error.type}: ${error.message} (${error.code})`);
  });
}

// Warnings don't prevent parsing but indicate issues
result.warnings.forEach(warning => {
  console.log(`Warning: ${warning.message} (${warning.code})`);
});

Security

The email parser includes security features:

• XSS Protection: HTML sanitization removes dangerous content
• Attachment Validation: File type and size restrictions
• Content Sanitization: Safe handling of text content
• Address Validation: Email address format checking

Performance

• Efficient parsing algorithms
• Memory-conscious attachment handling
• Processing time tracking
• Component-based parsing metrics

Dependencies

• iconv-lite - Character encoding conversion
• zod - Schema validation

Integration Status

• Logger integration: not-applicable - Email parser is a utility package focused on parsing operations; @bernierllc/logger integration would add unnecessary overhead to core parsing functions with graceful degradation
• Docs-Suite: ready - Full API documentation available in TypeScript format with comprehensive examples
• NeverHub integration: not-applicable - Email parser is a stateless utility package with no service discovery or event publishing requirements; @bernierllc/neverhub-adapter not needed but detectNeverHub patterns available

License

Copyright (c) 2025 Bernier LLC. All rights reserved.