# 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

```bash
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/
PYTHONPATH=src python3 -m email_connect.cli scan-mailbox --config config/mailbox.example.yml --expected-recipients tests/fixtures/expected_recipients.txt --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/`.

Expected recipients are optional. When provided as a text file or CSV, reports
include a `known_recipient` column, place known recipients first, and add
`undef.no_signal` diagnostics for expected recipients with no mailbox evidence.
See [Mailbox Report Tutorial](docs/mailbox-report-tutorial.md).

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`.
- Optional expected-recipient text/CSV input, `known_recipient` report
  filtering, no-evidence diagnostics, and datetime range filtering.
- Golden fixture tests for hard bounce, soft bounce, delayed delivery, final
  failure, complaint, unsubscribe, challenge-response, unknown return,
  parse-failure, 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.