Mbox Claims Correspondence Timeline Extractor

Parse Gmail/Outlook .mbox email exports into a threaded, chronological correspondence timeline ready for insurance claim audits, disputes, and court submissions.

What It Does

• Reads any standard .mbox file (Gmail Takeout, Outlook export, Thunderbird, Apple Mail, etc.)
• Extracts every email's metadata: date, sender, recipients, CC, subject, body snippet
• Groups emails into reply threads using In-Reply-To and References headers
• Filters emails by claim keywords (e.g. "claim", "policy", "loss") — or include all
• Produces:
  • Structured records (chronological, thread-annotated JSON)
  • CSV artifact — importable into Excel, case management systems
  • HTML report — printable, shareable compliance document

Who Buys This

Buyer	Use case
Insurance claims managers	Reconstruct correspondence history for disputed claims
Insurance lawyers / solicitors	Prepare chronological evidence bundles for litigation
Loss adjusters	Audit email trails for fraud detection or subrogation
Compliance teams	Evidence packs for FCA/FOS/court submissions

Scope & Limitations

• Input: local .mbox file only — no live mailbox, no IMAP/POP, no OAuth, no credentials, no network access
• Threading: resolved via standard email headers (Message-ID, In-Reply-To, References)
• Body: plain-text snippet only (first 300 chars); no PDF/attachment reading
• Volume: processes up to max_emails messages (default 5,000) as a safety cap
• Deterministic, reproducible output from the same input file

Local Demo

# 1. Export your mailbox to .mbox format (Gmail Takeout / Outlook / Thunderbird)

# 2. Run — no install needed, pure Python 3.10+ stdlib
python3 main.py '{
  "mbox_path": "/path/to/your/export.mbox",
  "claim_keywords": ["claim", "policy", "loss", "settlement"],
  "max_emails": 5000
}'

# 3. Full output including CSV and HTML artifacts
python3 - <<'EOF'
import json
from main import run
result = run({
    "mbox_path": "/path/to/your/export.mbox",
    "claim_keywords": ["claim"],
    "max_emails": 5000
})
print(f"Emails: {result['stats']['total_emails']}")
print(f"Threads: {result['stats']['total_threads']}")
with open("timeline.csv", "w") as f:
    f.write(result["csv_artifact"])
with open("timeline.html", "w") as f:
    f.write(result["html_artifact"])
print("Saved timeline.csv and timeline.html")
EOF

Test Command

$pytest tests/ -v

Supplying your mailbox (on the Apify platform)

A local file path means nothing in a cloud run — your mailbox isn't on the actor's filesystem. Supply your .mbox export one of two private ways:

1. Key-value store (most private) — upload your export to this run's key-value store and pass its key as mbox_kvs_key. Recommended for sensitive claims correspondence.
2. Paste — paste the raw export into mbox_text (best for small mailboxes; stays in your run input).

Your mbox never leaves your Apify account — this actor makes zero outbound network calls. It never uploads, forwards, or fetches your correspondence from anywhere. (URL ingestion for very large mailboxes is a planned future option.)

The default run uses a bundled DEMO sample so you can see the output shape immediately, before supplying real data.

Input Schema

Field	Type	Required	Description
mbox_kvs_key	string	❌	Key of an mbox record you uploaded to this run's key-value store (most private)
mbox_text	string	❌	Raw .mbox content pasted directly (small exports)
mbox_path	string	❌	Local filesystem path; defaults to the bundled DEMO sample. For local runs only — meaningless on the platform
claim_keywords	array of strings	❌	Filter to emails containing any keyword (empty = all emails)
max_emails	integer	❌	Maximum emails to process (default: 5000)

Supply one mbox source. If none is given, the run uses the bundled DEMO sample. The chosen source is recorded in the run's SUMMARY (never silent).

Output

Field	Description
records	List of email dicts, chronological, thread-annotated
threads	Dict of thread_id → list of message_ids
stats	Summary: total emails, threads, date range
csv_artifact	CSV text of the full timeline
html_artifact	Standalone HTML report for printing/sharing

On the Apify platform these map to:

• Dataset — one row per email on the timeline (chronological, thread-annotated). This is the billable unit.
• Key-value store — SUMMARY (stats + thread index), TIMELINE_HTML (the shareable report), TIMELINE_CSV (the full timeline as CSV).

A run that matches no correspondence fails loudly with a clear message and is not billed — never a silent empty result.

Pricing (pay-per-event)

Event	Price
Actor start	USD $0.10 per run
Correspondence item	USD $0.05 per email placed on the timeline (one dataset row each)

You pay only for what you time-line. A typical claim file of ~40 emails works out to about USD $2.10 per timeline (start + 40 items) — costs scale honestly with the size of the correspondence, no flat fee for a two-email dispute. No subscription, no unused-seat waste.