Skip to main content

MBOX Format (Mailbox)

Description​

MBOX is a format for storing collections of email messages. It's a simple format where multiple email messages are concatenated in a single file, with each message starting with a "From " line. MBOX is commonly used by email clients like Thunderbird.

File Extensions​

  • .mbox - MBOX mailbox files

Implementation Details​

Reading​

The MBOX implementation:

  • Uses Python's built-in mailbox module
  • Parses MBOX format
  • Extracts individual email messages
  • Converts each email to a dictionary
  • Handles email headers and body
  • Requires file path (not stream)

Writing​

Writing support:

  • Creates MBOX files
  • Writes email messages to mailbox
  • Requires file path (not stream)

Key Features​

  • Multiple messages: Can contain multiple email messages
  • Email format: Designed for email storage
  • Header extraction: Extracts email headers
  • Body handling: Handles email body content
  • Nested data: Supports complex email structures

Usage​

from iterable import open_iterable

# Basic reading
with open_iterable('mailbox.mbox') as source:
    for email in source:
        print(email)  # Contains email headers and body

# Writing
with open_iterable('output.mbox', mode='w') as dest:
    dest.write({
        'from': 'sender@example.com',
        'to': 'recipient@example.com',
        'subject': 'Test',
        'body': 'Message body'
    })

Parameters​

  • encoding (str): File encoding (default: utf8)

Limitations​

  1. File path required: Requires filename, not stream
  2. Email focus: Designed for email data, not general data
  3. Format complexity: Email structure can be complex
  4. Memory usage: Large mailboxes may use significant memory

Compression Support​

MBOX files can be compressed with all supported codecs:

  • GZip (.mbox.gz)
  • BZip2 (.mbox.bz2)
  • LZMA (.mbox.xz)
  • LZ4 (.mbox.lz4)
  • ZIP (.mbox.zip)
  • Brotli (.mbox.br)
  • ZStandard (.mbox.zst)

Use Cases​

  • Email archiving: Archiving email messages
  • Email migration: Migrating email between systems
  • Email analysis: Analyzing email collections
  • Backup: Backing up email messages

Error Handling​

  • Missing dependency: optional libraries raise ImportError with an install hint (pip install 'iterabledata[<extra>]' when an extra exists).
  • Write mode: read-only formats raise WriteNotSupportedError or ValueError when opened with mode="w".
  • Bad or unsupported input: may raise ValueError, OSError, or library-specific errors.
  • See Troubleshooting for decoding, detection, and engine issues.
  • EML - Single email format
  • MHTML - Web archive format