email-connect/INTENT.md

# INTENT.md

## Project Name

**email-connect**

## Purpose

`email-connect` is a headless email communication and evidence service.

It provides practical tooling for sending, tracking, querying, diagnosing, and managing email communication while also implementing the adapter contract needed to integrate naturally with `coordination-engine`.

The project treats email as a useful but uncertain communication channel. It can provide evidence that an email was accepted, rejected, bounced, opened, clicked, replied to, complained about, or suppressed, but it must not overclaim what email can prove.

The core principle is:

> Email events are evidence, not result satisfaction. `email-connect` reports email-channel facts and uncertainty. `coordination-engine` evaluates intended results.

## Primary Utility

`email-connect` should be useful in two modes.

### Standalone Mode

As a standalone tool, `email-connect` provides a generic API and UI to use, manage, inspect, and query email communication.

It should help users and systems:

* send transactional and notification emails
* manage message templates and send requests
* track message timelines
* inspect provider events
* classify bounces
* manage suppressions
* inspect recipient endpoint quality
* diagnose delivery uncertainty
* classify opens and clicks conservatively
* handle complaints, unsubscribes, replies, and out-of-office messages
* query message history and evidence
* expose email-channel health and diagnostics

The standalone product should be practically useful even without `coordination-engine`.

### coordination-engine Adapter Mode

As an adapter, `email-connect` implements `AdapterInterfaceSpecification.md` and emits normalized evidence events for `coordination-engine`.

It should provide:

* adapter descriptor
* capability profile
* evidence ceiling
* native status mappings
* action execution for email notifications
* normalized evidence events
* endpoint quality signals
* advisory email evidence assessments
* late-event handling
* adapter health reporting
* golden tests for overclaim prevention

## Strategic Role

`email-connect` is the first reference adapter for the broader coordination framework.

It should prove that adapters can be independently useful tools while still fitting cleanly into `coordination-engine`.

Strategically, `email-connect` should become:

```text
practical email communication tooling
+ provider-neutral email abstraction
+ evidence-normalization service
+ coordination-engine reference adapter
```

It should not become a full marketing automation platform or newsletter campaign manager. The focus is transactional, operational, coordination-related email communication and evidence handling.

## Core Principle

Email is a weak-to-medium evidence channel for awareness.

`email-connect` must distinguish:

```text
provider acceptance
recipient mail-server acceptance
temporary deferral
hard bounce
soft bounce
async bounce
provider drop
suppression
complaint
unsubscribe
open tracking
proxy/privacy open
scanner click
unverified click
human-like reply
out-of-office response
```

It must avoid treating technical email delivery as human awareness.

Important distinctions:

```text
provider accepted ≠ recipient server accepted
recipient server accepted ≠ inbox placement
inbox placement ≠ human awareness
open event ≠ human reading
click event ≠ authenticated recipient action
email reply ≠ legally valid acceptance
```

## Intended Users

The project is intended for:

* developers integrating email into applications
* operators monitoring transactional email flows
* product teams building coordination-heavy applications
* support teams diagnosing email delivery problems
* automation agents sending and inspecting email communication
* `coordination-engine` as a consuming orchestration runtime
* future UI users who need to query and manage email communication

## Primary Use Cases

### Send Email Notifications

Accept send requests through a generic API and dispatch them through one or more email providers.

### Track Message Timelines

Maintain a timeline of all known events for an email message:

```text
created
rendered
accepted by adapter
accepted by provider
queued
recipient MX accepted
deferred
bounced
opened
clicked
replied
complained
suppressed
```

### Diagnose Delivery Uncertainty

Expose useful diagnostics without pretending that email proves delivery or awareness.

Examples:

```text
recipient MX accepted but no engagement
privacy-proxy open only
scanner-like click detected
hard bounce received
async bounce arrived late
recipient reported missing email
```

### Normalize Provider Events

Translate provider-specific events into email-native events and then into coordination-compatible `EvidenceEvent` records.

### Manage Suppressions

Track suppression states caused by:

```text
hard bounce
spam complaint
unsubscribe
manual suppression
provider policy suppression
```

### Manage Endpoint Quality

Track email endpoint quality signals:

```text
syntax validity
domain/MX quality
hard-bounce history
complaint history
engagement history
suppression state
catch-all suspicion
role/shared address suspicion
```

### Provide Coordination Evidence

Emit normalized events for `coordination-engine`, such as:

```text
notification.attempt.accepted_by_provider
notification.endpoint.accepted
notification.endpoint.rejected_permanent
notification.endpoint.deferred
interaction.proxy_or_privacy_interaction
interaction.scanner_or_bot_interaction
interaction.unverified_actor_interaction
interaction.reply_received
notification.channel.complaint_received
notification.channel.suppression_added
```

### Provide Generic UI

Provide or enable a generic UI for:

* viewing sent messages
* searching communication history
* inspecting message timelines
* viewing provider status
* reviewing bounces and complaints
* managing suppressions
* inspecting endpoint quality
* diagnosing uncertain delivery
* querying evidence events
* checking adapter health

## Scope

`email-connect` should include:

* provider-neutral email send API
* message and attempt records
* provider abstraction layer
* provider event ingestion
* native event preservation
* native-to-normalized status mapping
* bounce classification
* suppression management
* open/click event classification
* scanner/proxy detection heuristics
* reply and out-of-office handling
* endpoint quality model
* message timeline API
* message assessment API
* adapter descriptor and health endpoints
* coordination-engine-compatible evidence event output
* basic UI for operational inspection and management

## Non-Goals

`email-connect` is not primarily:

* a newsletter platform
* a marketing automation suite
* a CRM
* a full workflow engine
* a legal notice system
* a document portal
* a payment system
* a signature system
* the owner of coordination case success

It may integrate with such systems, but its core responsibility is email communication and email-channel evidence.

## Architecture Direction

The project should be organized around these internal components:

```text
email-connect
  email-api
  email-ui
  provider-abstraction
  message-store
  event-ingestion
  native-status-mapping
  evidence-normalizer
  evidence-assessment
  endpoint-quality
  suppression-manager
  template-manager
  tracking-manager
  adapter-contract
  provider-health
```

## Provider Abstraction

`email-connect` should support multiple email providers through provider modules.

Provider modules should handle:

* sending
* provider message IDs
* provider webhooks
* provider event verification
* bounce event parsing
* complaint handling
* suppression handling
* provider-specific statuses
* provider health

The internal model should not be hardcoded to one provider.

Provider event mapping should follow:

```text
provider-native event
→ email-native event
→ EmailEvidenceAssessment
→ coordination EvidenceEvent
```

## Evidence and Uncertainty Model

`email-connect` should provide an email-native assessment.

```text
category:
  success
  fail
  undef
```

The `undef` category is normal and important.

Common `undef` subclasses:

```text
undef.pending
undef.provider_accepted_only
undef.queued
undef.deferred
undef.endpoint_accepted_only
undef.no_signal
undef.weak_positive
undef.proxy_open
undef.scanner_click
undef.unverified_click
undef.identity_uncertain
undef.possibly_spam_or_quarantine
undef.possibly_silent_drop
undef.forwarding_unknown
undef.catch_all_domain
undef.conflicting_evidence
undef.channel_degraded
undef.recipient_reported_missing
undef.out_of_office
```

Email evidence must be classified conservatively.

## Evidence Ceiling

`email-connect` should declare the following evidence ceiling by default:

```yaml
max_positive_event: interaction.unverified_actor_interaction
max_positive_strength: medium
can_prove_human_awareness: false
can_prove_payload_access: false
can_prove_payload_delivery: false
can_prove_identity: false
can_prove_authority: false
can_prove_non_repudiation: false
```

Stronger evidence should come from other systems, such as:

* portal login
* authenticated document download
* payment settlement
* signature completion
* explicit verified acknowledgement

## coordination-engine Compatibility

`email-connect` should implement `AdapterInterfaceSpecification.md`.

It should provide:

```text
AdapterDescriptor
AdapterCapabilityProfile
AdapterActionCapability
AdapterActionRequest handling
AdapterActionResult
AdapterEvent
EvidenceEvent
AdapterEvidenceAssessment
EvidenceGrade
EvidenceCeiling
NativeStatusMapping
EndpointQuality
AdapterHealth
CorrelationContext
LateEventPolicy
FeatureDependency
GoldenTests
```

The adapter should support at least:

```text
notification.send
notification.send_reminder
notification.register_tracking_context
recipient.suppress
recipient.unsuppress
```

## Generic API Direction

The generic API should support:

```text
POST /email/send
GET /email/messages
GET /email/messages/{id}
GET /email/messages/{id}/timeline
GET /email/messages/{id}/assessment
GET /email/endpoints/{id}/quality
POST /email/suppressions
DELETE /email/suppressions/{id}
GET /email/channel-health
```

Adapter-compatible API concepts should include:

```text
GET /adapter/descriptor
GET /adapter/health
POST /adapter/actions
POST /adapter/events/provider
GET /adapter/events
```

The exact API shape may evolve, but these conceptual operations should remain stable.

## Generic UI Direction

The UI should initially be simple and operational.

Core views:

```text
Message list
Message detail
Message timeline
Evidence assessment
Endpoint quality
Suppression list
Provider health
Event search
Bounce/complaint diagnostics
Adapter compatibility
```

The UI should help humans and agents answer questions such as:

```text
What happened to this email?
Was it rejected, bounced, accepted, opened, clicked, or replied to?
Is the recipient endpoint healthy?
Is the channel suppressed?
Is this a real engagement signal or likely proxy/scanner activity?
What evidence can this email provide?
What can it not prove?
```

## MVP Focus

The first implementation should prove the useful standalone value and the coordination adapter value.

Recommended MVP:

1. Accept send requests.
2. Store email message records.
3. Dispatch through simulated provider or one real provider.
4. Preserve idempotency.
5. Ingest provider events.
6. Normalize provider events.
7. Generate email evidence assessments.
8. Emit coordination-compatible evidence events.
9. Provide message timeline API.
10. Provide endpoint quality basics.
11. Provide suppression basics.
12. Provide adapter descriptor and health.
13. Provide minimal UI for inspecting messages and timelines.

## MVP Acceptance Criteria

The MVP is useful when it can:

* send or simulate email sending
* record a message timeline
* ingest provider events
* classify provider acceptance as weak evidence
* classify MX acceptance as weak technical evidence
* classify hard bounce as strong failure evidence
* classify proxy opens and scanner clicks as ambiguous
* preserve raw event references
* avoid overclaiming awareness
* expose a useful API
* expose a basic inspection UI
* integrate with `coordination-engine` as an adapter

## Design Priorities

1. **Practical usefulness**
   The system should be useful for real email communication management, not only adapter testing.

2. **Provider neutrality**
   Avoid binding the core model to one provider.

3. **Evidence correctness**
   Never overclaim what email proves.

4. **Operational visibility**
   Make message timelines, bounces, complaints, and suppressions easy to inspect.

5. **Coordination compatibility**
   Fit naturally into `coordination-engine` through the adapter contract.

6. **Agent friendliness**
   Provide clear schemas, mappings, APIs, and golden tests.

7. **Security and privacy**
   Protect credentials, message content, endpoint data, tracking links, and raw provider events.

## Guiding Statement

`email-connect` is a practical email communication and evidence service. It sends and tracks email, normalizes provider events, exposes useful operational APIs and UI, and integrates with `coordination-engine` by reporting conservative email-channel evidence under uncertainty.