coulomb/email-connect
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Headless email communication and evidence service.
19 commits 1 branch 0 tags 348 KiB
Find a file
tegwick 208b4ae4cc Normalize agent instructions and workplan frontmatter (STATE-WP-0067) 
- Align agent files with on-disk workplan prefixes (infer from workplan ids)
- Set workplan domain to registered domain_slug; add topic_slug where applicable
- Repair frontmatter delimiter formatting; migrate legacy task status literals
- Regenerate AGENTS.md, CLAUDE.md, and .claude/rules from State Hub templates
2026-06-22 23:16:24 +02:00
.claude/rules Normalize agent instructions and workplan frontmatter (STATE-WP-0067) 2026-06-22 23:16:24 +02:00
config feat: add expected recipient reporting 2026-06-02 03:07:13 +02:00
docs feat: add expected recipient reporting 2026-06-02 03:07:13 +02:00
registry Add capability registry scaffold (REUSE-WP-0014-T04 B02) 2026-06-16 01:52:17 +02:00
reports feat: start mailbox evidence scanner 2026-06-02 01:19:09 +02:00
spec Seeded repo with intent and PRD 2026-06-01 23:56:07 +02:00
src/email_connect feat: add expected recipient reporting 2026-06-02 03:07:13 +02:00
tests feat: add expected recipient reporting 2026-06-02 03:07:13 +02:00
workplans Normalize agent instructions and workplan frontmatter (STATE-WP-0067) 2026-06-22 23:16:24 +02:00
.custodian-brief.md chore(consistency): sync task status from DB [auto] 2026-06-02 02:43:38 +02:00
.gitignore feat: start mailbox evidence scanner 2026-06-02 01:19:09 +02:00
.repo-classification.yaml Mark .repo-classification.yaml human-reviewed (CUST-WP-0050 T02) 2026-06-22 11:40:44 +02:00
AGENTS.md Normalize agent instructions and workplan frontmatter (STATE-WP-0067) 2026-06-22 23:16:24 +02:00
CLAUDE.md Normalize agent instructions and workplan frontmatter (STATE-WP-0067) 2026-06-22 23:16:24 +02:00
INTENT.md Seeded repo with intent and PRD 2026-06-01 23:56:07 +02:00
LICENSE Initial commit 2026-06-01 21:37:38 +00:00
pyproject.toml feat: start mailbox evidence scanner 2026-06-02 01:19:09 +02:00
README.md feat: add expected recipient reporting 2026-06-02 03:07:13 +02:00
SCOPE.md chore: register with state hub 2026-06-02 00:36:01 +02:00

README.md

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/
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.

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.