MBOX to EML Parser

A TypeScript parser that converts MBOX (Apple Mail Export) files to EML format. This tool can parse MBOX files and convert individual email messages to standard EML files.

Features

• Parse MBOX files (Apple Mail Export format)
• Convert to individual EML files
• Preserve email headers and metadata
• Handle multiple email addresses (To, Cc, Bcc)
• Support for custom encoding and file size limits
• Command-line interface
• TypeScript support with full type definitions
• Comprehensive test coverage
• MIT License

Installation

npm install

Usage

Command Line Interface

# Convert MBOX file to multiple EML files
npx ts-node src/cli.ts inbox.mbox ./eml-files

# Convert to single EML file (first message only)
npx ts-node src/cli.ts inbox.mbox ./eml-files --single

# With custom options
npx ts-node src/cli.ts inbox.mbox ./eml-files --encoding utf8 --max-size 50000000

Programmatic Usage

import { MboxToEmlConverter, convertMboxToEml } from './src/index';

// Method 1: Using the main converter class
const converter = new MboxToEmlConverter();
const outputFiles = await converter.convertMboxToEmlFiles(
  './inbox.mbox',
  './eml-files'
);

// Method 2: Using the convenience function
const outputFiles = await convertMboxToEml('./inbox.mbox', './eml-files');

// Method 3: Parse messages first, then convert
const messages = await converter.parseMboxFile('./inbox.mbox');
const outputFiles = await converter.convertMessagesToEmlFiles(messages, './eml-files');

Advanced Usage with Custom Options

import { MboxToEmlConverter } from './src/index';

const converter = new MboxToEmlConverter(
  {
    encoding: 'utf8',
    maxFileSize: 50 * 1024 * 1024, // 50MB
    preserveHeaders: true
  },
  {
    includeHeaders: true,
    formatDate: true,
    encoding: 'utf8'
  }
);

const outputFiles = await converter.convertMboxToEmlFiles('./inbox.mbox', './eml-files');

API Reference

MboxToEmlConverter

Main class that combines MBOX parsing and EML conversion.

Constructor

new MboxToEmlConverter(
  mboxOptions?: MboxParserOptions,
  emlOptions?: EmlConverterOptions
)

Methods

• convertMboxToEmlFiles(mboxFilePath: string, outputDir: string): Promise<string[]>
• convertMboxToEmlFile(mboxFilePath: string, outputFilePath: string): Promise<string>
• parseMboxFile(mboxFilePath: string): Promise<EmailMessage[]>
• convertMessagesToEmlFiles(messages: EmailMessage[], outputDir: string): Promise<string[]>

Types

EmailMessage

interface EmailMessage {
  from: string;
  to: string[];
  cc?: string[];
  bcc?: string[];
  subject: string;
  date: Date;
  messageId: string;
  headers: Record<string, string>;
  body: string;
  attachments?: EmailAttachment[];
}

MboxParserOptions

interface MboxParserOptions {
  encoding?: BufferEncoding;
  maxFileSize?: number;
  preserveHeaders?: boolean;
}

EmlConverterOptions

interface EmlConverterOptions {
  includeHeaders?: boolean;
  formatDate?: boolean;
  encoding?: BufferEncoding;
}

CLI Options

• --single: Convert only the first message to a single EML file
• --encoding <encoding>: Set file encoding (default: utf8)
• --max-size <bytes>: Maximum file size in bytes (default: 100MB)
• --no-headers: Don't include email headers in output
• --no-preserve-headers: Don't preserve original headers
• --no-format-date: Don't format dates in headers
• --help: Show help message

Development

Prerequisites

• Node.js 16 or higher
• npm or yarn

Setup

# Clone the repository
git clone https://github.com/harshit-budhraja/mbox-to-eml-parser.git
cd mbox-to-eml-parser

# Install dependencies
npm install

# Build the project
npm run build

Testing

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

Code Quality

# Lint the code
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run format

Build

# Build the project
npm run build

# Clean build artifacts
npm run clean

Project Structure

mbox-to-eml-parser/
├── src/                    # Source code
│   ├── types.ts           # TypeScript interfaces
│   ├── mbox-parser.ts     # MBOX parsing logic
│   ├── eml-converter.ts   # EML conversion logic
│   ├── index.ts           # Main API and convenience functions
│   ├── cli.ts            # Command-line interface
│   └── example.ts        # Usage examples
├── tests/                 # Test files
│   ├── fixtures/         # Test data files
│   ├── mbox-parser.test.ts
│   ├── eml-converter.test.ts
│   ├── integration.test.ts
│   └── setup.ts          # Test setup
├── dist/                 # Compiled JavaScript (generated)
├── coverage/             # Test coverage reports (generated)
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── jest.config.js        # Jest configuration
├── .eslintrc.js         # ESLint configuration
├── .prettierrc          # Prettier configuration
├── LICENSE              # MIT License
└── README.md            # This file

Testing

The project includes comprehensive tests covering:

• Unit Tests: Individual component testing
• Integration Tests: End-to-end workflow testing
• Edge Cases: Error handling and boundary conditions

Test Coverage

• MBOX parsing with various formats
• EML conversion with different options
• File handling and error scenarios
• CLI functionality
• Integration workflows

Running Tests

# Run all tests
npm test

# Run specific test file
npm test tests/mbox-parser.test.ts

# Run tests with coverage
npm run test:coverage

Examples

Basic Example

import { convertMboxToEml } from './src/index';

async function convertEmails() {
  try {
    const outputFiles = await convertMboxToEml('./inbox.mbox', './eml-files');
    console.log(`Converted ${outputFiles.length} messages`);
  } catch (error) {
    console.error('Conversion failed:', error);
  }
}

Working with Individual Messages

import { MboxToEmlConverter } from './src/index';

async function processMessages() {
  const converter = new MboxToEmlConverter();
  const messages = await converter.parseMboxFile('./inbox.mbox');
  
  for (const message of messages) {
    console.log(`From: ${message.from}`);
    console.log(`Subject: ${message.subject}`);
    console.log(`Date: ${message.date}`);
    console.log('---');
  }
}

File Formats

MBOX Format

MBOX is a standard format for storing email messages. Each message starts with a "From " line and contains email headers followed by the message body.

Example:

From [email protected] Mon Jan 01 12:00:00 2025
From: "John Doe" <[email protected]>
To: "Jane Smith" <[email protected]>
Subject: Test Email
Date: Mon, 01 Jan 2025 12:00:00 +0000

This is the email body.

EML Format

EML is a standard format for individual email messages, commonly used by email clients.

Example:

From: "John Doe" <[email protected]>
To: "Jane Smith" <[email protected]>
Subject: Test Email
Date: Mon, 01 Jan 2025 12:00:00 +0000

This is the email body.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow TypeScript best practices
• Write comprehensive tests for new features
• Ensure all tests pass before submitting PR
• Follow the existing code style (enforced by ESLint and Prettier)
• Update documentation as needed

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Harshit Budhraja

• GitHub: @harshit-budhraja

Acknowledgments

• Built with TypeScript for type safety
• Uses Jest for comprehensive testing
• Follows open source best practices