mbox-md

Convert a Gmail Takeout (or other) .mbox archive into one Markdown file per message, organized by year and month, with attachments stored once and shared across messages.

Install

uv tool install mbox-md     # or: pipx install mbox-md

To use it as a library, pip install mbox-md (or uv add mbox-md). Requires Python 3.11+.

Usage

CLI:

mbox-md "All mail Including Spam and Trash.mbox" archive/
mbox-md takeout.mbox.zst archive/ --since 2020-01-01 --strip-quotes
mbox-md takeout.mbox --dry-run            # counts and output size, writes nothing
mbox-md takeout.mbox archive/ --compress-source zstd --delete-source

Input can be plain, zstd, or gzip; compression is detected from the file's contents and handled in-process by compress-utils, with no zstd or gzip command needed.

API:

import mbox_md

stats = mbox_md.convert("All mail.mbox", "out/")

for raw in mbox_md.iter_messages("All mail.mbox"):
    msg = mbox_md.parse_message(raw)  # None if it's in Spam or Trash

Development

uv sync
uv run pytest            # unit tests, fabricated data only
uv run pytest -m local   # smoke test against local-data/takeout-sample.mbox, if you have it
uv run mypy              # strict type checking
uv run coverage run -m pytest && uv run coverage combine && uv run coverage report   # branch coverage, 95% minimum
uv run ruff check src tests && uv run ruff format --check src tests

License

MIT