Email mbox backfill

The batch half of email capture: a one-shot import of an mbox archive, complementing the live Email / IMAP connector. There's no cap_connectors row involved — it's a CLI command you run once (or re-run with a later --since date) — and it shares the same normalization as the live connector, so backfilled and live-polled mail end up as identical cap_items shapes.

What it does

Reads one or more .mbox files with Python's stdlib mailbox module, filters messages by their Date header, and normalizes each into a cap_items row. No network, no credentials.

Prereqs

An mbox export of the mailbox you want to backfill — for example a Google Takeout export of Gmail, which produces one .mbox file per label/folder.

Run it

python -m capture_agent.backfill email --mbox ~/takeout/ --since 2026-01-01

--mbox accepts either a single .mbox file or a directory — if it's a directory, every *.mbox file inside it is read. --since filters to messages on or after that date (YYYY-MM-DD); a message with a missing or unparseable Date header is skipped.

Verify

The command prints a summary when it finishes, e.g. capture email backfill: {'ingested': N, 'skipped_dupe': 0, 'unrouted': N, 'entities_created': N, 'errors': 0}. Check cap_items in the PocketBase admin for the new rows.

Errors

Per-message parsing/normalization failures are logged and skipped so one bad message never aborts the whole import — re-running the same command later is safe, since cap_items dedupes by external_id and already-imported messages are left alone.