email-connect/SCOPE.md

# SCOPE

## One-liner

`email-connect` is a headless, provider-neutral email communication and
evidence service for sending, tracking, diagnosing, and normalizing email
events.

---

## Core Idea

Email is useful evidence, but it is not proof of human awareness or business
result satisfaction. This repository exists to model email as an uncertain
communication channel: preserve raw provider events, normalize email-native
facts, classify weak or suspicious engagement signals conservatively, and emit
coordination-compatible evidence for downstream orchestration.

The product should be useful both as a standalone operational email service and
as the first reference adapter for `coordination-engine`.

---

## In Scope

- Provider-neutral transactional and notification email send API.
- Message, attempt, raw event, and timeline records.
- Provider webhook/event ingestion and native status mapping.
- Normalized email evidence events for coordination workflows.
- Bounce, deferral, complaint, unsubscribe, and suppression handling.
- Endpoint quality signals for email addresses and recipient endpoints.
- Conservative open, click, reply, scanner, proxy, and privacy classification.
- Adapter descriptor, capability profile, evidence ceiling, and health reporting.
- Generic APIs and future UI surfaces for operators, support teams, agents, and developers.

---

## Out of Scope

- Newsletter campaign management or broad marketing automation.
- Claiming inbox placement, human reading, authenticated recipient action, or legal acceptance from email telemetry alone.
- Evaluating whether the intended business result was satisfied; that belongs to `coordination-engine`.
- Becoming a provider-specific dashboard clone.
- Owning non-email communication channels.

---

## Relevant When

- A system needs to send transactional or coordination-related email without binding directly to one provider.
- Operators need to inspect what happened to a message across provider, MX, bounce, suppression, open, click, and reply events.
- Agents or services need queryable email-channel evidence with explicit uncertainty.
- `coordination-engine` needs an email adapter that emits normalized evidence events and declares evidence ceilings.

---

## Not Relevant When

- The goal is bulk marketing, newsletter design, campaign segmentation, or growth automation.
- The system needs proof of recipient awareness, legal acceptance, or business outcome completion.
- A single provider dashboard is sufficient and provider-neutral modeling is unnecessary.
- The work is about another notification channel such as SMS, push, chat, or postal mail.

---

## Current State

- Status: active for two shipped slices. The broader provider API and UI in
  this intent are not built.
- Mailbox scanner: `python3 -m email_connect.cli scan-mailbox` reads a fixture
  directory or a mailbox over read-only IMAP, classifies return mail, and
  writes CSV reports plus local SQLite. It does not mark mail seen and it
  does not send.
- Transactional receiver: `src/email_connect/transactional.py` is the live
  HTTP service in namespace `email-connect` on railiance01. Callers with an
  admitted policy send fixed templates through authenticated SMTP. The SQLite
  ledger records attempts, verifications, and suppressions. SMTP acceptance
  is not inbox receipt. See `deploy/k8s/railiance/README.md`.
- MAS evidence: `src/email_connect/mas_gateway_evidence.py` maps one MAS
  gateway event into this service's evidence ceiling
  (`docs/mas-email-evidence-v0.1.json`). The MAS facility stays the receiver
  for `mas.coulomb.social`. This service does not parse statutes or send
  MAS syntax.
- Stability: the two slices and the evidence mapping are in use. The generic
  `POST /email/send` API, provider webhooks, template manager, and UI stay
  intent until a workplan builds them.

---

## How It Fits

- Upstream dependencies: email providers, provider webhooks, adapter interface expectations, coordination evidence vocabulary.
- Downstream consumers: `coordination-engine`, automation agents, product systems, operators, support users, audit/compliance reviewers.
- Often used with: State Hub workplans, future `coordination-engine` adapter contracts, provider-specific email integrations.

---

## Terminology

- Preferred terms: email evidence, message timeline, provider acceptance, MX acceptance, deferral, hard bounce, soft bounce, suppression, complaint, privacy open, scanner click, unverified interaction, evidence ceiling.
- Also known as: email adapter, email evidence service, provider-neutral email layer.
- Potentially confusing terms: "delivered" must be decomposed into provider/MX facts; "opened" must not imply human reading; "clicked" must not imply authenticated recipient action.

---

## Related / Overlapping

- `coordination-engine` - expected downstream evaluator of intended results and consumer of normalized email evidence.
- `llm-connect` - sibling `*-connect` style adapter/service pattern in the custodian domain.
- `state-hub` - tracks repo registration, workplans, progress, and consistency for this repository.

---

## Getting Oriented

- Start with: `INTENT.md`.
- Key files / directories: `spec/ProductRequirementsDocument.md`, `workplans/`, `AGENTS.md`.
- Entry points: `python3 -m email_connect.cli`, `src/email_connect/transactional.py`, `deploy/k8s/railiance/README.md`.

---

## Provided Capabilities

```capability
type: service
title: Provider-neutral email communication
description: Send transactional and coordination-related email through a stable provider-neutral interface while preserving provider-specific evidence for diagnosis.
keywords: [email, transactional-email, notification, provider-neutral, communication]
```

```capability
type: evidence
title: Email event normalization
description: Normalize raw provider events into conservative email-channel evidence, distinguishing acceptance, deferral, bounce, suppression, complaint, open, click, and reply signals.
keywords: [email, evidence, normalization, bounce, suppression, tracking]
```

```capability
type: adapter
title: coordination-engine email adapter
description: Provide the adapter descriptor, capability profile, evidence ceiling, health reporting, and normalized evidence events needed by coordination-engine.
keywords: [coordination-engine, adapter, evidence-ceiling, notification, email]
```

---

## Notes

The core product discipline is semantic restraint: report what the email channel
knows, preserve uncertainty, and leave result evaluation to downstream
coordination logic.

## Generated work-record index

This repository opts into staged-source WORK-RECORDS.md generation through
`.generated-work-records.json` and the isolated `.generated-work-records.mk`
recipe. `make generated-work-records` reuses the State Hub renderer through
the Custodian adapter; `make generated-work-records-check` verifies byte-exact
agreement with staged Markdown. The pre-commit hook uses the isolated recipe,
preserves unstaged index edits by refusing them, and retains the generated-only
commit guard. It does not contact the hub, alter workplan statuses, or grant
deployment authority. This consumes shared tooling; it does not make this
repository the provider of the generator capability.

## Local orientation brief policy — 2026-10-21

`.custodian-brief.md` is a local, ignored State Hub orientation snapshot. Refreshing
it does not require a Git commit. Authored workplans and the generated
WORK-RECORDS index keep their existing source and staged-generation contracts.