coulomb/email-connect
5
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Headless email communication and evidence service.
97 commits 1 branch 0 tags 988 KiB
Find a file
tegwick c0c3221855
Some checks failed
Transactional mail acceptance / mail (push) Failing after 53s
Details
CI Smoke / host-smoke (push) Successful in 1s
Details
CI Smoke / container-smoke (push) Successful in 2s
Details
Prepare native sender adapter and verify snapshot integration 
Assistant: codex
Assistant-Model: gpt-6-astra
Assistant-Session: 01a18e2d-f513-7742-b8e7-12af0b744ff3
2026-10-31 17:02:48 +01:00
.claude/rules docs: workplan-first agent guidance prose (CUST-WP-0055 T04 batch 5) 2026-07-08 19:51:18 +02:00
.forgejo/workflows Implement P05 checked services and safe selected delivery recovery 2026-09-13 22:11:49 +02:00
config Prepare glob-scoped callers and prove offsite ledger recovery 2026-10-09 11:43:11 +02:00
deploy Wave-2 right-sizing: email-connect CPU request 25m->5m (EMAIL-WP-0009) 2026-10-21 23:59:51 +02:00
docs Prepare native sender adapter and verify snapshot integration 2026-10-31 17:02:48 +01:00
intakes docs: retain provider setup delivery owner intake 2026-10-19 13:16:55 +02:00
registry Declare the live release units for this owner. 2026-10-23 15:49:53 +02:00
reports feat: start mailbox evidence scanner 2026-06-02 01:19:09 +02:00
scripts Prepare native sender adapter and verify snapshot integration 2026-10-31 17:02:48 +01:00
spec Seeded repo with intent and PRD 2026-06-01 23:56:07 +02:00
src/email_connect Prepare glob-scoped callers and prove offsite ledger recovery 2026-10-09 11:43:11 +02:00
tests Prepare native sender adapter and verify snapshot integration 2026-10-31 17:02:48 +01:00
workplans Prepare native sender adapter and verify snapshot integration 2026-10-31 17:02:48 +01:00
.generated-work-records.json Adopt staged WORK-RECORDS generation and catch the index up. 2026-10-28 00:30:50 +01:00
.generated-work-records.mk Adopt staged WORK-RECORDS generation and catch the index up. 2026-10-28 00:30:50 +01:00
.gitignore chore: keep generated orientation brief local 2026-10-21 12:31:16 +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 docs(agents): repoint remote State Hub URL to the in-cluster address 2026-08-25 00:20:54 +02:00
CLAUDE.md Normalize agent instructions and workplan frontmatter (STATE-WP-0067) 2026-06-22 23:16:24 +02:00
Containerfile Implement P05 checked services and safe selected delivery recovery 2026-09-13 22:11:49 +02:00
DECISIONS.md EMAIL-WP-0005-T02: add GreenMail test harness 2026-08-14 01:41:38 +02:00
INTENT.md Seeded repo with intent and PRD 2026-06-01 23:56:07 +02:00
LICENSE Adopt Target Revenue Source License V1C1 (org-wide preliminary rollout) 2026-07-30 00:05:52 +02:00
pyproject.toml Implement transactional invitation mail service 2026-08-09 21:28:41 +02:00
README.md feat: add expected recipient reporting 2026-06-02 03:07:13 +02:00
SCOPE.md Adopt staged WORK-RECORDS generation and catch the index up. 2026-10-28 00:30:50 +01:00
WORK-RECORDS.md Prepare durable sender transition and current-ledger recovery protocol 2026-10-31 16:41:30 +01: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.