generated from coulomb/repo-seed
141 lines
5.5 KiB
Markdown
141 lines
5.5 KiB
Markdown
# 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.
|