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:

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:

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:

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:

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:

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:

hard bounce
spam complaint
unsubscribe
manual suppression
provider policy suppression

Manage Endpoint Quality

Track email endpoint quality signals:

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:

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:

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:

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

Evidence and Uncertainty Model

email-connect should provide an email-native assessment.

category:
  success
  fail
  undef

The undef category is normal and important.

Common undef subclasses:

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:

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:

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

The adapter should support at least:

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

Generic API Direction

The generic API should support:

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:

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:

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:

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.