[Decision] Make HayaSend the customer-owned, agent-safe email control plane

[yhay81]

Status

Accepted on 2026-07-26 by @yhay81. This issue is the current product-direction decision and should guide roadmap, review, and new implementation work.

Linear is normally the Haya agent system's durable source of truth, but its connection currently requires reauthentication. Until this decision is synchronized there, this GitHub issue is the canonical record.

Decision

HayaSend is not another email delivery provider or a feature-for-feature Resend clone.

HayaSend is the customer-owned safety and reliability control plane between applications / AI agents and email delivery providers.

Proposed short promise:

One email API. Your cloud. Any provider.

HayaSend should provide a stable Resend-compatible API while the data plane remains in the user's Cloudflare or AWS account. Cloudflare Email Service, Amazon SES, and later optional providers perform delivery; HayaSend owns reliable semantics, policy, audit, lifecycle normalization, and portability.

Target user and job

Small technical teams and agent-driven applications that want modern email API ergonomics without surrendering infrastructure ownership, operational visibility, or provider choice.

Core job:

Deploy a reliable email API in my cloud in minutes, use an existing Resend SDK, know why every message was sent and what happened to every recipient, and change delivery provider without changing application code.

Product principles

1. Customer-owned data plane — message bodies and attachments remain in the customer's cloud account; no Haya service is required in the send path.
2. Compatibility as distribution, not identity — preserve Resend SDK compatibility, but compete on reliability, safety, ownership, and portability.
3. Reliable and honest semantics — idempotency, transactional outbox, leases, retry classification, monotonic state, replay, and explicit documentation of unavoidable at-least-once boundaries.
4. Recipient-level truth — model message, recipient, delivery attempt, provider event, and webhook delivery separately. Aggregate message status is derived, not canonical.
5. Capability-aware providers — expose provider limits and supported events instead of pretending that SES and Cloudflare have identical features.
6. Agent-safe by design — separate draft/send permissions, recipient policies, rate/cost budgets, approval gates, sensitive-content controls, kill switches, and immutable actor/intent audit.
7. Operational proof over feature count — publish conformance, failure-injection, cost, recovery, and real dogfood evidence.
8. Honest adoption guidance — document when a direct Cloudflare binding or SES call is simpler and HayaSend is unnecessary.

Architecture direction

Keep the core runtime-neutral and separate ports/adapters for:

• API contract and validation
• metadata store
• payload store
• job queue / scheduler
• mail transport
• provider lifecycle events
• webhook delivery
• policy and audit

Initial provider targets:

• Cloudflare: Workers + Hono, D1, R2, Queues/DLQ, Email Sending binding/API, Email event subscriptions
• AWS: API Gateway/Lambda, DynamoDB, S3, SQS/EventBridge, SES/SNS

Required public artifacts:

• HayaSend Compatibility Contract covering behavior, not only endpoint shapes
• provider capability matrix (maxMessageBytes, maxRecipients, event support, scheduling, tracking)
• conformance suite and published per-adapter results
• fault model and recovery runbook
• safe deploy / doctor / upgrade / rollback workflow

Priority order

Now: production semantics

• repair idempotency + enqueue failure boundaries with an outbox/reconciliation model
• monotonic recipient-level delivery state under duplicate and out-of-order events
• correct permanent vs retryable error classification
• public contract and property/conformance tests
• scoped credentials and safe production deployment gate
• reconcile the existing stacked PRs before adding more breadth

Next: Cloudflare proof

• Cloudflare adapter using D1/R2/Queues/Email Sending
• event correlation from provider messageId to HayaSend message and recipient
• provider-specific 5 MiB / 50-recipient validation and capability reporting
• signed normalized webhooks and replay
• cost/limit reporting and doctor
• safe one-command deployment and rollback
• FolioMCP dogfood for non-critical notifications: PDF completion/failure, sharing, quota warnings, and operator alerts

Then: agent-safe policy

• actor/application/agent/intent identity
• email:draft, email:send, and external-send scopes
• recipient/domain allowlists and deny rules
• hourly/daily send and cost budgets
• approval requirements for external, sensitive, attachment, or high-volume sends
• sandbox sink, preview, kill switch, and immutable audit
• MCP interface only after the underlying policy and delivery semantics are trustworthy

Explicitly deferred / non-goals

Until production semantics and the Cloudflare + FolioMCP proof are complete, do not prioritize:

• visual template builder and broad template-product work
• marketing campaigns, contacts, audiences, or journeys
• full inbound email product
• simultaneous expansion to many language SDKs
• broad CRUD CLI parity beyond deploy/doctor/send/inspect/recover
• SMS, push, chat, or a general notification-workflow builder
• managed multi-tenant content data plane
• custom MTA, IP warming, or delivery network

Existing work in these categories does not need to be discarded, but should be parked or merged only when it clearly supports the accepted core direction without delaying it.

Business boundary

Keep the Apache-2.0 data plane open. Future paid value should be aligned with BYOC rather than a second per-email transport fee:

• fleet/version/drift/health management
• safe upgrades and rollback
• compliance, audit, and advanced policy
• production support/SLA
• migration, failure drills, and deliverability reviews
• certified provider adapters

A future management plane should receive health/version/cost metadata only by default, not message content.

Success metrics

Primary outcome:

Number of production workloads that can change provider without application-code changes while retaining an auditable, recipient-level delivery history.

Operational gates:

• time to first delivered test email
• official SDK compatibility/conformance pass rate
• duplicate sends per million
• queue-to-provider latency and event lag
• recovery time from failed deploy or provider incident
• provider migration time
• operator time per 10,000 sends
• message-body leakage incidents (target: zero)

Instruction to active agents

Treat this decision as the roadmap boundary. Complete in-flight work safely, but do not create additional breadth-first features without mapping them to Now / Next / Then above. Before merging the current PR stack, propose which PRs should be merged now, rebased/combined, or parked. The immediate next deliverable should be a focused execution plan for production semantics and the Cloudflare/FolioMCP proof, not another parity feature.

[yhay81]

Execution plan published for review in #84.

It follows this decision's required order:

1. ship the protected AWS beta without weakening Ship the v0.1 beta through the production-safety gate #22;
2. make commit/dispatch recoverable with a transactional outbox;
3. replace aggregate-only lifecycle storage with recipient, attempt, and provider-event truth;
4. publish a capability-aware conformance contract;
5. prove it on Cloudflare Workers/D1/R2/Queues/Email Sending;
6. dogfood non-critical FolioMCP notifications and a provider migration;
7. add agent policy and MCP only after those gates.

The plan also classifies every one of the 23 post-v0.1 drafts. #49/#51/#53 become one ordered production-semantics series; inbound expansion and the extra language-SDK lane are parked. The Apache-2.0 data plane keeps deploy/doctor/upgrade/rollback/conformance, while optional paid value is limited to content-blind fleet operations, compliance, and accountable support.

PR #84 remains a post-v0.1 Draft based on release/v0.1.0; it does not alter or bypass release PR #30.