# 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: concept / planning - Implementation: intent and PRD only - Stability: evolving - Usage: none yet The repository currently contains product intent and requirements. No runtime stack, API implementation, persistence model, provider integration, or UI has been committed yet. --- ## 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: no code entry points yet. --- ## 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.