mbox-extractor

📬 Recursively extract all attachments from .mbox email archives with a single command

Features

• Recursive scanning - Finds all .mbox files in any directory tree
• Safe filenames - Sanitizes attachment names, removing illegal characters
• No duplicates - Uses content-based hashing to prevent overwrites
• Progress display - Visual progress bar for large mailboxes

Quick Start

uv tool install mbox-extractor

mbox-extractor /path/to/emails

Installation

Using uv (recommended)

uv tool install mbox-extractor

Using pip

pip install mbox-extractor

From source

git clone https://github.com/tsilva/mbox-extractor.git
cd mbox-extractor
uv tool install .
pre-commit install

Usage

Extract all attachments from .mbox files under a directory:

mbox-extractor /path/to/search

Attachments from each .mbox file are saved to a folder with the same name:

Found mbox: /emails/archive.mbox -> extracting to /emails/archive
Extracting archive.mbox: 100%|████████████████████| 500/500 [00:10<00:00, 48.5it/s]
Extracted 42 attachments to '/emails/archive'.

How It Works

1. Recursively scans the given path for .mbox files
2. Opens each mailbox and iterates through all messages
3. Extracts attachments with sanitized, unique filenames
4. Saves them to a folder named after the source .mbox file

Filenames are made unique by appending an 8-character MD5 hash of the file content, preventing overwrites when multiple attachments share the same name.

Programmatic Usage

You can also use mbox-extractor as a library in your Python code:

from mbox_extractor import extract_mbox

# Extract with default output directory (creates /path/to/archive/ from /path/to/archive.mbox)
count = extract_mbox("/path/to/archive.mbox")

# Extract to a custom output directory
count = extract_mbox("/path/to/archive.mbox", output_dir="/custom/output")

# Extract without progress bar (for scripts/automation)
count = extract_mbox("/path/to/archive.mbox", show_progress=False)

API

extract_mbox(mbox_path: str, output_dir: str | None = None, show_progress: bool = True) -> int

Requirements

• Python 3.12+
• tqdm (installed automatically)

License

MIT