email-connect

Headless, provider-neutral email communication and evidence service.

The first implementation slice is the Mailbox Evidence Scanner MVP: scan a return mailbox or fixture directory, classify inbound email-channel evidence, store scan state locally, and generate timestamped CSV reports without overclaiming delivery, awareness, or coordination success.

Quickstart

PYTHONPATH=src python3 -m unittest discover -s tests
PYTHONPATH=src python3 -m email_connect.cli adapter-descriptor
PYTHONPATH=src python3 -m email_connect.cli scan-mailbox --config config/mailbox.example.yml --out reports/

The example config uses tests/fixtures/mailbox as a mailbox source. Runtime state is written to .email-connect/state.sqlite; generated CSV reports are written to reports/.

For a live mailbox, set mailbox.protocol: imap, configure host, port, folder, and credential environment variable names, then export the credentials before running scan-mailbox. IMAP scans select the configured folder read-only and fetch message bodies with BODY.PEEK[]; mailbox write-back actions such as marking messages seen are intentionally unsupported in this MVP.

Current Scope

• Coordination-engine spec review and references.
• Initial adapter descriptor, capability profile, evidence ceiling, and limitations.
• Fixture and read-only IMAP mailbox sources.
• Conservative mailbox message parser and evidence mapper.
• SQLite state store with scan cursor, message/evidence deduplication, and endpoint quality hints.
• CSV report generation, including --report-only-new.
• Golden fixture tests for hard bounce, soft bounce, delayed delivery, final failure, complaint, unsubscribe, unknown return, out-of-office, and human reply signals.

Provider webhooks, outbound sending, suppression workflows, OAuth mailbox login, and a UI remain outside this first mailbox-scanner slice.