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.

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

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]

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]

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.

5.5 KiB Raw Permalink Blame History