# 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.