cloudflare-email 0.1.0 → 0.3.0

data/docs/outbox.md

@@ -0,0 +1,175 @@
+# Durable outbound email for Rails
+
+The optional Active Record layer supplies immutable send snapshots, single-attempt delivery claims, recipient outcomes, delivery-event receipts, and audited reconciliation. Use it when background retries, process crashes, or missing provider responses must not silently resend an email. The plain Ruby client and ordinary ActionMailer delivery method remain available without these tables.
+
+This is delivery infrastructure. Your application still authorizes sending, decides what belongs in a conversation, reviews drafts, and controls operator access.
+
+## Install
+
+After configuring the gem's sending credentials, generate both sets of tables:
+
+```sh
+bin/rails generate cloudflare:email:tracking
+bin/rails generate cloudflare:email:outbox
+bin/rails db:migrate
+```
+
+Skip a generator whose migration is already installed. The outbox initializer requires `cloudflare/email/active_record`, which loads the models, `Outbox`, `prepare_mail`, and `DeliveryEvents`, and also loads both jobs. For manual setup without the generator, require:
+
+```ruby
+require "cloudflare/email/active_record"
+require "cloudflare/email/send_job"
+require "cloudflare/email/replay_events_job"
+```
+
+Use a durable ActiveJob backend and a recurring scheduler suitable for your application. The gem does not install a job backend or Cloudflare Queue subscription. Configure delivery events and the separate queue token as described in [delivery-events.md](delivery-events.md).
+
+## Prepare once, dispatch after commit
+
+Render the mail, snapshot it together with your application update, and enqueue only after the outer database transaction commits:
+
+```ruby
+outbox = Cloudflare::Email::ActiveRecord::Outbox
+account_id = Cloudflare::Email::Credentials.account_id
+
+# Inside an application service that runs outside an existing transaction:
+delivery = nil
+Draft.transaction do
+  draft.lock!
+  # Apply the application's owner/approval checks here.
+  mail = ReplyMailer.reply(draft).message
+  delivery = outbox.prepare_mail(
+    account_id: account_id,
+    operation_key: "draft:#{draft.id}:revision:#{draft.revision}",
+    mail: mail
+  )
+  draft.update!(outbound_operation_key: delivery.operation_key)
+end
+
+Cloudflare::Email::SendJob.perform_later(account_id, delivery.operation_key)
+```
+
+`Draft`, `revision`, and `outbound_operation_key` above are application examples, not generated gem models. For nested application transactions, use an actual after-commit hook; returning from an inner transaction does not necessarily commit the outer one.
+
+`prepare_mail` accepts a rendered `Mail::Message` or an ActionMailer message delivery. It reads the SMTP envelope and encodes the MIME once, preserving attachments and To/Cc/Bcc delivery. It rejects `perform_deliveries == false`. Mailer rendering callbacks run during rendering; delivery callbacks are bypassed when sending the saved snapshot. Put required delivery authorization before preparation or in your application service.
+
+For an existing MIME source:
+
+```ruby
+delivery = outbox.prepare(
+  account_id: account_id,
+  operation_key: "invoice:123:notification:1",
+  from: "billing@example.com",
+  recipients: ["customer@example.net"],
+  mime_message: raw_mime
+)
+```
+
+The account plus operation key identifies one immutable attempt. Preparing the same envelope and MIME returns the existing operation. Changing its snapshot raises `Outbox::SnapshotConflict`. Recipient order is preserved, duplicate addresses are removed, domains are lowercased, and local parts retain their case. MIME is stored as binary data. Re-rendering a mail can change generated headers, so job retries use the saved operation identity instead of calling the mailer again.
+
+`Outbox.deliver(delivery, client: optional_client)` sends synchronously and refuses an ambient database transaction. Its `prepared → sending` claim commits before network I/O. A supplied client must match the account and expose `retry_ambiguous == false`. The standard `SendJob` uses the configured sending account/token and forces ambiguous retries off; applications managing several Cloudflare accounts can use their own account-aware job and pass the appropriate client.
+
+## States and retries
+
+| Operation state | Meaning and permitted action |
+| --- | --- |
+| `prepared` | Snapshot saved; safe to dispatch. |
+| `sending` | A process claimed the attempt. Another job cannot send it. A crashed process can leave this state indefinitely. |
+| `accepted` | All recipients have acceptance evidence. Repeated delivery returns the record without a network request. |
+| `partial` | Some recipients have acceptance evidence, while others were rejected or remain unknown. Repeated delivery never resends the batch. |
+| `rejected` | Available outcomes show rejection. The operation is terminal; correcting and sending again requires a new operation key. |
+| `unknown` | Acceptance cannot be established safely. Investigate and reconcile before deciding on another attempt. |
+| `confirmed_not_sent` | An operator confirmed the whole operation was not sent. Old jobs stay blocked; a deliberate new attempt needs a new key. |
+
+Each `outbound_recipients` row stores `acceptance_state` separately from lifecycle `state`. A later complaint or bounce must not erase evidence that the original send was accepted. Lifecycle `occurred_at` stays nil for immediate send results and operator reconciliation: local clock time is not a provider event timestamp.
+
+Malformed success responses, conflicting provider message IDs, timeouts, ambiguous transport errors, and failures saving an accepted response remain uncertain. Explicit supported provider rejection responses can produce `rejected`. Errors are re-raised after recording the conservative outcome. A database outage may leave the already committed `sending` claim instead of `unknown`; both block resend.
+
+This is not exactly-once delivery. Provider acceptance and a database commit cannot be one transaction. Client pre-send/rate-limit retry behavior remains available, but automatic ambiguous retries are prohibited by the outbox.
+
+## Recover dispatch and application projections
+
+An application can commit its snapshot and crash before enqueueing. Schedule a scan of `prepared` operations and enqueue their saved identities. Multiple scanners/jobs are safe because only one can claim an operation. Do not reset `sending` operations merely because they are old.
+
+Operational commands:
+
+```sh
+bin/rails cloudflare:email:pending_deliveries
+OPERATION_KEY='invoice:123:notification:1' bin/rails cloudflare:email:deliver
+bin/rails cloudflare:email:replay_events
+```
+
+The listing includes prepared, sending, unknown, and partial operations for the configured account; it does not automatically dispatch them. `deliver` uses `SendJob.perform_now` with the saved snapshot.
+
+Optional Rails callbacks reduce application glue:
+
+```ruby
+settings = Rails.application.config.x.cloudflare_email
+settings.outbox_delivery_handler = ->(delivery) {
+  # Idempotently project the saved operation into application records.
+}
+settings.outbox_recipient_handler = ->(delivery, recipient) {
+  # Project a lifecycle change into application records.
+}
+```
+
+The delivery callback runs under a delivery row lock after the result has been saved. If application projection fails after acceptance, retrying the job repairs the projection without another provider send. The recipient callback runs inside receipt processing's transaction. Keep callbacks idempotent and use the same database connection for atomic application writes. External side effects cannot be rolled back; schedule them through a durable application mechanism.
+
+## Consume and replay events
+
+Wire the supplied projector into the event consumer:
+
+```ruby
+settings = Rails.application.config.x.cloudflare_email
+settings.event_handler = ->(event) {
+  Cloudflare::Email::ActiveRecord::DeliveryEvents.record(event) do |delivery, recipient|
+    settings.outbox_recipient_handler&.call(delivery, recipient)
+  end
+}
+```
+
+`DeliveryEvents.record` commits the receipt before projecting it. Callback failures roll back projection and leave the saved receipt available for retry. It matches the account, normalized provider Message-ID, and recipient; ambiguous matches remain unmatched. Known events apply with lifecycle ordering and terminal-state guards. Event identity provides durable deduplication. Unknown future event statuses remain unmatched for later support.
+
+An event may arrive before the send result is saved. `SendJob` replays matching receipts after its delivery callback, and a recurring `ReplayEventsJob.perform_later(account_id)` covers later recovery. Direct callers can use:
+
+```ruby
+Cloudflare::Email::ActiveRecord::DeliveryEvents.replay(
+  account_id: account_id, message_id: delivery.provider_message_id
+) do |operation, recipient|
+  # Optional application projection.
+end
+```
+
+Message-ID normalization removes surrounding angle brackets; it is correlation, not authorization. No provider ID means there is no safe automatic provider-ID match.
+
+## Reconcile uncertainty
+
+Restrict this operation to an authorized application operator. The gem records the supplied actor string; it does not authenticate that actor or verify external evidence.
+
+```ruby
+outbox.reconcile(
+  delivery,
+  outcome: :accepted,
+  actor: "User:42",
+  reason: "Provider support confirmed acceptance",
+  evidence: "Support ticket 123 and retained provider response",
+  provider_message_id: "provider-message-id",
+  recipients: ["customer@example.net"]
+) do |operation|
+  # Optional application update, atomic with the audit and state change.
+end
+```
+
+`outcome: :accepted` requires a valid provider Message-ID. `outcome: :not_sent` requires evidence of nonacceptance. Actor, reason, and evidence must be nonempty strings. Reconciliation can run inside an application transaction; callbacks and audit writes roll back together if it fails. Existing audit records are read-only through the model.
+
+For a partial operation, only unresolved recipients can be reconciled. Omit `recipients` to select the unresolved subset. Known outcomes and lifecycle state are preserved; later decisions can resolve another unknown subset. A conflicting provider ID is refused. A batch with all recipients confirmed not sent becomes `confirmed_not_sent`; a mixed batch remains partial or otherwise reflects the remaining acceptance evidence. Never retry a complete partial batch to reach one unresolved recipient.
+
+For a `sending` operation, first stop the original sender and verify it cannot resume. Reconciliation additionally requires `confirm_sender_stopped: true` and a claim at least 15 minutes old. Elapsed time alone is insufficient. There is no automatic lease expiry or timeout-based resend.
+
+## Data ownership and migration
+
+The gem owns its operation, recipient, receipt, and reconciliation infrastructure. The inbox owns mailbox permissions, conversations, approval policy, AI drafts, and UI. Link product records to operations by a stable key or application foreign key instead of copying the ledger algorithm.
+
+The MIME snapshot contains email bodies, addresses, and attachments. Apply your application's database access, encryption, backup, and retention policies. Removing ledgers or replaying old backups can discard uncertainty and deduplication evidence; quiesce sending and reconcile provider activity during recovery.
+
+Importing historical attempts is application-specific. If the old application did not save exact MIME, a reconstructed snapshot is historical metadata, not proof of the original bytes. Preserve its known/unknown state and do not turn imported accepted or uncertain attempts into dispatchable `prepared` operations. The generated outbox and receipt migrations refuse rollback to preserve delivery and deduplication evidence; use a forward fix or a reconciled backup.

data/docs/routing-deliveries.md

@@ -0,0 +1,94 @@
+# Confirm delivery to verified Routing destinations
+
+Cloudflare can deliver mail to a verified Email Routing destination through Routing without producing an Email Sending delivery callback. You can keep using the recipient's normal address. Do not remove its verified destination or rewrite the recipient to obtain a callback.
+
+The optional Routing Analytics integration confirms **positive delivery to the receiving mail server** from authenticated Cloudflare analytics. It does not prove inbox placement or that a person read the message. Missing analytics leave the outcome unresolved; they never authorize a resend or provider fallback.
+
+## Enable it
+
+The plain Ruby client needs no Rails or Active Record dependency:
+
+```ruby
+require "cloudflare/email/routing_analytics"
+
+client = Cloudflare::Email::RoutingAnalytics::Client.new(
+  account_id: ENV.fetch("CLOUDFLARE_ACCOUNT_ID"),
+  zone_id: ENV.fetch("CLOUDFLARE_ANALYTICS_ZONE_ID"),
+  api_token: ENV.fetch("CLOUDFLARE_ANALYTICS_TOKEN")
+)
+client.verify_account!
+```
+
+Use a separate token with **Zone Analytics Read and Zone Read**, restricted to the sending zone. The client verifies that the zone belongs to the supplied account before querying analytics. Keep sending and queue credentials separate. A token is never written into a receipt.
+
+For durable Rails tracking, install the outbox first, then generate the additional receipt table:
+
+```sh
+bin/rails generate cloudflare:email:outbox # only if not already installed
+bin/rails generate cloudflare:email:routing_tracking
+bin/rails db:migrate
+```
+
+Receipts encrypt their JSON evidence using Rails Active Record Encryption. Configure the application's `active_record.encryption.primary_key`, `deterministic_key`, and `key_derivation_salt` before recording receipts (Rails' `db:encryption:init` task generates keys). Keep keys in credentials or protected environment configuration and back them up separately. There is no plaintext fallback enabled by this integration. Receipt metadata includes account and operation identifiers; protect the database and backups as usual.
+
+The generated initializer explicitly requires `cloudflare/email/active_record/routing_deliveries`. Installing the gem alone enables no scheduler, network request, tracking table, or tenancy behavior.
+
+## Collect and apply evidence
+
+Run network requests outside database transactions. The durable outbox must have retained the accepted operation's SMTP envelope and provider Message-ID:
+
+```ruby
+tracking = Cloudflare::Email::ActiveRecord::RoutingDeliveries
+
+client.delivery_evidence(
+  message_id: delivery.provider_message_id,
+  since: delivery.request_started_at,
+  until_time: Time.now.utc
+).each do |evidence|
+  receipt = tracking.record(delivery: delivery, evidence: evidence)
+  tracking.apply(receipt) do |saved_delivery, recipient|
+    # Optional business projection using this same database connection.
+    # Read recipient.state; do not send mail or call external services here.
+  end
+end
+```
+
+`record` commits the original evidence before projection. Repeating it returns the same receipt. A changed authentic event under the same identity, or association with another operation, raises an error. Query windows and other rows returned alongside that event may differ between polls without creating duplicate receipts. Client payloads retain the complete original response envelope, provider row, authenticated account/zone, source, and query window and are immutable through ordinary model updates.
+
+`apply` returns `:applied`, including successful replay. It updates only a nonterminal recipient and marks the receipt applied in the same transaction. It preserves the accepted operation, envelope snapshot, and every existing terminal webhook fact, including a bounce. Thus `:applied` means evidence was processed; inspect the recipient's actual state. A later genuine Sending complaint continues to update the recipient through the existing Sending event API.
+
+Callbacks run only when the recipient changes. Same-database callback errors roll back the recipient, business writes, and receipt completion together; the original pending receipt remains available. A callback must not send email or perform external effects.
+
+This is not a webhook endpoint: accept evidence only from the authenticated client or your protected durable storage. Constructing an `Evidence` object validates its shape and correlation, not its provenance. Never deserialize arbitrary incoming request bodies into trusted analytics evidence.
+
+## Retry projection fairly
+
+```ruby
+result = tracking.replay(account_id: account_id, limit: 100, after_id: saved_cursor)
+result.errors.each do |failure|
+  ErrorReporter.report(failure[:error], receipt_id: failure[:receipt_id])
+end
+save_cursor(result.finished ? 0 : result.after_id)
+```
+
+The batch is bounded to 1–1,000 receipts. Failed receipts advance the cursor, allowing later receipts to proceed. After a complete pass, reset the cursor and revisit failures. Errors remain visible in the return value; your application must report them. Supply the same optional projection callback when replaying. Give fresh analytics discovery a separate scheduling opportunity so repeated projection failures cannot starve new evidence. No database transaction is interrupted by an HTTP or polling timeout.
+
+The client uses a five-second total network deadline, five-second socket timeouts, a 1,000,000-byte streamed response cap and no implicit HTTP retry. A failed request is visible to your scheduler. Queries returning 100 rows are rejected as potentially truncated; use a narrower historical window and retain existing unresolved records. Plan availability, analytics retention and sampling can limit what Cloudflare can prove.
+
+## Deliberately conservative matching
+
+The initial API requires exactly one accepted saved SMTP-envelope recipient, exactly one matching accepted operation in the account, matching sender and normalized provider Message-ID, and a nonempty provider session ID. The event must be `newEmail`, `delivered`, final, unsampled and not an NDR. Its timestamp must fall inside the requested historical window and at or after the saved request start, rounded down to Cloudflare's second precision.
+
+MIME `To` and analytics `to` are never used as envelope identity. Multi-recipient operations, sampled rows, forwarding rows and missing events do not become guessed delivery or failure. Malformed, truncated, conflicting or wrongly scoped qualifying evidence raises. Terminal delivery can override an equal or later nonterminal observation; existing terminal facts stay intact.
+
+## Tenant and cross-database applications
+
+Multi-tenancy remains off by default. If enabled, use the existing `Tenancy.with` or `Mailboxes.for_tenant` context for every outbox and Routing receipt operation, and install the receipt migration in each tenant database. Record instances cannot be moved between tenant contexts. A separate analytics account does not select or authorize a tenant.
+
+The gem checks provider-ID uniqueness inside the selected database. If one Cloudflare account spans several tenant databases, the host must also enforce account-wide provider-ID uniqueness in its shared directory or ledger before calling `record`. Tenant-local lookup alone cannot establish that a matching operation is unique across independent databases.
+
+An application may reserve an explicit physical storage key for system mail, such as `_system_outbound`, using its existing tenant provisioning and backup process. That storage key is not an organization or authorization identity. Keep nil tenant context fail-closed; do not silently map it to shared storage. Reserve and validate the key in the host application so a customer cannot claim it.
+
+For business records on another database, keep the host's own durable intake/projection record. Commit the gem evidence and projection in the selected tenant database, then finish the host projection. If the second commit fails, replay the same gem evidence and finish the host work independently. The gem's callback will not run again after its receipt was applied. There is no distributed transaction or exactly-once external effect guarantee.
+
+Cloudflare references: [Email event subscriptions](https://developers.cloudflare.com/email-service/platform/event-subscriptions/) and [metrics and analytics](https://developers.cloudflare.com/email-service/observability/metrics-analytics/).

data/docs/routing-diagnostics.md

@@ -0,0 +1,68 @@
+# Check whether an address is configured to reach your Worker
+
+This diagnostic is available in gem version 0.3.0.
+
+A mailbox registered in Rails is not proof that Cloudflare can deliver to it.
+Use this read-only check when onboarding a receiving domain, investigating a
+missing message, or checking an existing catch-all before activating addresses.
+
+```sh
+bin/rails cloudflare:email:check_route \
+  ADDRESS=houston@customer.example.com \
+  WORKER_NAME=cloudflare-email-ingress-production \
+  ACCOUNT_ID=your-cloudflare-account-id
+```
+
+Configure your Cloudflare management token in the normal gem credentials. The
+inspection needs Zone Read, DNS Read, and Email Routing Read permissions. No Edit
+permissions are needed. `WORKER_NAME` defaults to the gem's environment-scoped
+Worker name; `ACCOUNT_ID` falls back to the configured account, if present.
+
+Every check reports `PASS`, `FAIL`, or `UNKNOWN`. The command exits zero only
+when all configuration checks pass. An unavailable API, insufficient permission,
+an unsupported matcher, or ambiguous rule ordering produces `UNKNOWN`, not a
+successful result. Output excludes raw provider responses and credentials.
+
+The check inspects:
+
+- The closest containing Cloudflare zone and its account when an expected account is supplied.
+- Whether Email Routing is enabled for the zone.
+- MX and SPF records for the **exact receiving domain**. Parent-domain records
+  cannot satisfy a subdomain's requirements, and a parent's unrelated MX provider
+  does not conflict with correctly configured subdomain records.
+- Active explicit address rules before falling back to the catch-all. An explicit
+  drop, forwarding action, or different Worker takes precedence over a correct
+  catch-all. Disabled explicit rules are ignored. Multiple matching rules or
+  unsupported matcher forms leave selection unverified rather than guessing
+  priority or tie behavior.
+
+List reads are paginated and bounded to 50 pages per endpoint, responses to 1 MiB,
+and each request to 20 seconds (with shorter connection/read timeouts). An
+incomplete inspection does not report success. This command only issues GET
+requests. It never enables routing, changes DNS, repairs rules, or activates
+mailbox records.
+
+## Use from Ruby
+
+```ruby
+require "cloudflare/email/routing_diagnostics"
+
+report = Cloudflare::Email::RoutingDiagnostics.new(
+  api_token: ENV.fetch("CLOUDFLARE_API_TOKEN")
+).check(
+  address: "houston@customer.example.com",
+  worker_name: "cloudflare-email-ingress-production",
+  account_id: ENV.fetch("CLOUDFLARE_ACCOUNT_ID")
+)
+
+report[:status] # "pass", "fail", or "unknown"
+report[:checks] # [{ name: "zone", status: "pass", message: "..." }, ...]
+```
+
+This API does not require Active Record or enable multi-tenancy. You can use it
+with a custom Worker and an existing application ingestion pipeline. It reports
+a provider configuration snapshot; it does **not** prove public DNS propagation,
+full SPF evaluation, successful live delivery, the Worker's application URL or
+behavior, or application acceptance. Keep those as separate checks, including a
+controlled end-to-end delivery when appropriate. A passing report does not
+automatically change mailbox readiness or constitute delivery evidence.

data/docs/tenant-mailboxes-plan.md

@@ -0,0 +1,149 @@
+# Tenant-aware mailbox layer — implementation proposal
+
+Status: original design record. The reusable mailbox module and tenant adapter
+are implemented on the feature branch; see [mailboxes](mailboxes.md) and
+[tenant setup](activerecord-tenanted.md) for the actual API. Rebulk application
+migration and live customer rollout remain separate work. Based on the gem's merged 0.2
+code and Rebulk/rebulk-system main at
+`17ffafccb69968dae022acdbb4620b84c65bedfb`.
+
+## Product goal
+
+Let a Rails application create, suspend and manage named mailboxes for its
+organizations, sites or users. Support organization subdomains such as
+`houston@venezia.rebulk.com`. Reuse the gem's transport, outbox and receipts;
+do not create another delivery ledger. SQLite remains the default integration
+target, including separate SQLite databases with `activerecord-tenanted`.
+
+## Rebulk already has the foundations
+
+- `Organization` is shared and carries `email_subdomain`.
+- `TenantRecord` uses `activerecord-tenanted` and requires a tenant context.
+- Sites have per-organization email local parts. `tracking@<org>.rebulk.com`
+  is an existing reserved organization-level destination.
+- `Customer` is a buyer within an organization, not the tenant root. A customer
+  mailbox can belong to that record without creating another tenant database.
+- ActiveStorage is tenant-specific. Mail must resolve its tenant before blob
+  access, persistence or job deserialization that needs tenant records.
+- `InboundEmail` records document-processing outcomes inside the tenant.
+  `CommunicationMessage` is a shared, encrypted cross-channel operational view.
+  Preserve these product roles instead of replacing them with duplicate models.
+- Existing ingest has its own Worker contract, sender authentication and
+  authorization, raw archive and document processing. It is not currently the
+  gem's ActionMailbox pipeline. Its policy cannot be discarded during migration.
+- `OrganizationEmailDomain` supports sign-in auto-join. Receiving-domain
+  ownership must be separate; creating a receiving domain must never grant users
+  membership or change login policy.
+
+## Database and routing boundary
+
+Keep a minimal shared receiving-domain directory: exact canonical domain,
+immutable tenant identity, tenant connection key, lifecycle state and provisioning
+evidence. Enforce domain ownership with a database uniqueness constraint. Never
+construct a SQLite path from an arbitrary recipient string or request parameter.
+
+Keep mailbox definitions, address aliases, message memberships, outbox records
+and tenant receipts in the tenant database. Support an application-selected
+ActiveRecord base class so every related gem model uses the intended connection.
+Merely wrapping today's hardcoded `ActiveRecord::Base` models in `with_tenant`
+does not establish that connection contract.
+
+The ingress sequence must be:
+
+1. Bound the body and verify the complete Worker signature and envelope.
+2. Resolve the exact signed recipient domain in the shared active directory.
+3. Enter the mapped tenant context, without creating a tenant implicitly.
+4. Resolve the registered active mailbox/alias inside that tenant.
+5. Persist raw mail and mailbox membership idempotently, then schedule processing.
+6. Restore tenant context even when processing raises.
+
+No MIME To/Cc, browser session fallback, sender domain or guessed organization
+slug may select the receiving tenant. Unknown/suspended domains and addresses
+must have explicit rejection or restricted quarantine outcomes, with no fallback
+to an arbitrary tenant/mailbox. Directory changes and mailbox suspension must
+also be checked when deferred work resumes; never silently reassign old mail.
+
+## Optional mailbox module
+
+Add explicit opt-in loading and a generator. The initial contract should cover:
+
+- Tenant/domain registration and verified provisioning state.
+- Mailbox creation, aliases, suspension and lookup by registered address.
+- Application ownership links for user/site/customer mailboxes, checked within
+  the resolved tenant; authenticated actor authorization stays in the host app.
+- Incoming message membership and deduplication without another copy of MIME.
+- Outgoing preparation through an active mailbox with an allowed From address,
+  linked to the existing outbox. A customer cannot select another tenant's
+  sender merely because both share the same Cloudflare account token.
+- An explicit tenant context adapter and connection-class configuration;
+  `activerecord-tenanted` is an optional integration, not a plain-Ruby dependency.
+
+Do not claim a finished inbox UI, IMAP/POP service, thread model, AI workflow,
+search engine or membership system. Rebulk supplies those product decisions.
+Document local-part case policy, reserved names and alias behavior before schema
+implementation; normalization must agree across directory, mailbox and send APIs.
+
+## Jobs, events and cross-database commits
+
+Jobs carry stable tenant and operation/mailbox identities. Establish tenant
+context before loading records. Never rely on a previous request's `Current`
+state, a naked numeric record ID or a Cloudflare account ID as a tenant key.
+Cloudflare account identity and application tenant identity are different.
+
+Queue events arrive without a Rails tenant context and may precede a saved send
+response. Use a shared durable receipt intake and a provider correlation
+directory populated by tenant outbox results. Retain unmatched events and retry
+when correlation becomes available; do not infer tenant ownership solely from
+the recipient's external domain. Ambiguous mappings remain unprojected.
+
+Delivery from shared intake to tenant projection is at least once. A tenant
+receipt deduplicates it. Mark shared processing complete only after tenant commit;
+crashes between commits cause safe replay. Writes to the shared directory,
+tenant SQLite and job queue are not one transaction. Recovery must cover each
+gap without allowing another send or prematurely acknowledging an event.
+
+## Customer subdomains and Cloudflare
+
+An organization may use a Rebulk-owned subdomain or, later, an explicitly verified
+customer-owned domain. Track receive readiness and send-domain verification
+separately. A Rails database record or wildcard DNS entry alone does not enable
+Cloudflare email routing or sending.
+
+Prefer explicit address rules for the first supported provisioner. Reconcile
+desired state with Cloudflare and retain failures for retry rather than marking
+a mailbox active before its route is ready. Multiple tenants may share a Worker
+and ingress secret within one application/environment; tenant routing stays in
+Rails. Separate Cloudflare accounts require account-aware credentials/jobs.
+
+The current catch-all task operates at zone scope. Do not alter the Rebulk apex
+catch-all or promise automatic subdomain catch-alls as part of mailbox creation.
+Verify provider support and limits for the exact subdomain topology before a
+live rollout. Custom domains need ownership verification and safe offboarding.
+
+## Implementation slices and acceptance checks
+
+1. **Tenant foundation:** configurable model connections, tenant-aware job
+   wrappers and migrations in the tenant migration path. Test two real SQLite
+   tenant databases with overlapping IDs, missing context, retries and cleanup.
+2. **Mailbox registry:** shared domain mapping plus tenant mailboxes/aliases,
+   lifecycle and ownership APIs. Test exact matching, uniqueness races,
+   suspension, reserved addresses and isolation for lookup and sending.
+3. **Tenant ingress:** authenticated envelope resolution before ActionMailbox
+   storage. Test Bcc routing, raw bytes, duplicate delivery, unknown destinations,
+   tenant-specific blob access and processing jobs after process restart.
+4. **Outbound/event integration:** reuse saved MIME/claims, enforce mailbox sender
+   identity, add durable shared-to-tenant event dispatch and repair scans. Test
+   event-before-response, duplicate receipts and crashes at each commit boundary.
+5. **Rebulk adoption:** map existing org/site addresses, preserve tracking and
+   sender-review policies, link existing communication/ingest records, and add
+   mailbox management through Rebulk's access resolver. Start behind a feature
+   flag on an isolated development address; keep current production routes intact.
+6. **Provisioning and live verification:** test domain/route setup with bounded
+   retries, then a real send/reply/attachment/event flow for two test tenants.
+   Verify the deployed revision and preserve a dated report before customer rollout.
+
+Required regressions include existing plain-Ruby, single-database SQLite and
+PostgreSQL behavior. Do not call the integration complete merely because a
+single-tenant send works. Existing Rebulk sender-authentication metadata must
+remain authenticated through the new Worker contract before its old ingress
+can be retired; the gem's v2 envelope alone does not supply that policy evidence.

data/docs/thread-correlation.md

@@ -0,0 +1,27 @@
+# Thread correlation
+
+Store the provider's returned `message_id` with the intended recipient and your
+application conversation. The ActionMailer delivery method updates the Mail
+object's message ID when Cloudflare returns one. Plain Ruby callers can read
+`response.message_id`.
+
+Normalize stored IDs and parsed `In-Reply-To` / `References` values with
+`Cloudflare::Email::MessageId.normalize(value)`. This removes surrounding whitespace
+and one complete angle-bracket pair; it preserves case. Parse multiple-ID headers
+with your mail parser first. Match `In-Reply-To` first, then `References` from most
+recent to oldest, scoped to the authenticated recipient's mailbox.
+
+Outgoing replies should set `In-Reply-To` and `References` using the parent
+message's ID. Keep unmatched replies available for application handling when an
+ID is missing or unknown. Send acceptance and saving the returned ID are not one
+atomic transaction.
+
+The old `SecureMessageId` helper was removed before the 0.2 release. Cloudflare
+controls Message-ID and our [live test](verification/2026-09-10-live.md) confirmed
+replacement of custom IDs for both raw MIME and ActionMailer sends. The provider's
+returned IDs matched received headers and supported reply correlation.
+
+Email headers locate a conversation; they do not authorize access to it. Scope
+lookups by the trusted SMTP recipient obtained through `Envelope.for(inbound)`.
+The SMTP envelope sender and MIME From header do not authenticate a person.
+Sensitive actions require your application's authentication and approval policy.

data/docs/troubleshooting.md

@@ -0,0 +1,104 @@
+# When email does not behave as expected
+
+Start by identifying which step failed: sending, incoming storage, mailbox
+processing, or delivery tracking. Those are separate pieces. Use test addresses
+you control, and avoid pasting tokens, raw MIME or private provider responses
+into public logs or issues.
+
+## Sending
+
+| What you see | What to check next |
+| --- | --- |
+| New generator or API is missing | Check `Gemfile.lock`. The new features require the [0.2 commit](getting-started.md#install-the-current-code); published 0.1.0 lacks them. |
+| Credentials appear to be ignored | Nonempty Rails credentials override environment variables. Check the Rails environment and restart the app after changes. |
+| Authentication or domain error | Run `bin/rails cloudflare:email:doctor`; check account ID, token permissions and sending-domain verification. |
+| `doctor` reports limited read access | A send token may lack diagnostic read permissions. Review the specific result; diagnostics alone cannot prove whether sending works. |
+| API accepted the message but nothing arrives | Inspect queued, bounced and suppressed recipient outcomes, then delivery events and the destination's spam folder. Acceptance is not final delivery. |
+| `deliver_later` does nothing | Check your job backend, running workers and failed jobs. For the outbox's `SendJob`, make sure a worker processes `mailers`. |
+| Timeout or server error | Cloudflare might have accepted the message before the error. Investigate before resending. The outbox preserves this uncertainty. |
+| Some recipients received it | Inspect each recipient; do not resend the entire partial batch. See [outbox recovery](outbox.md#reconcile-uncertainty). |
+
+To perform a deliberate real-send check:
+
+```sh
+FROM=hello@mail.example.com TO=you@example.net bin/rails cloudflare:email:send_test
+```
+
+## Incoming email
+
+| What you see | What to check next |
+| --- | --- |
+| Address receives nothing | Verify receiving-subdomain onboarding and the address route's Worker. Sending-domain verification is separate. |
+| Route provisioning refuses a subdomain | Complete Email Routing subdomain setup and DNS preflight first. Do not enable or replace apex routing just to bypass the error. |
+| Worker reports 401 from Rails | Check matching ingress secrets and compatible signature versions. The Worker defaults to v2. The opt-in v3 [custom-ingress API](custom-ingress.md) requires upgrading Rails before enabling Worker metadata. |
+| Worker reports 408 | Check clock accuracy and the five-minute signing window. |
+| Worker reports 413 or rejects size | Raw MIME exceeds the configured limit. Match `MAX_EMAIL_BYTES` on Rails and Worker and check upstream request limits. |
+| Worker reports 3xx | Point it directly at the final HTTPS ingress URL; redirects are intentionally rejected. |
+| Worker times out | Check Rails availability and request latency. Direct mode can reject mail; the default [durable inbound path](../templates/worker/README.md#durable-inbound-delivery) retains it in R2 for retry and scheduled recovery. |
+| Rails returns 200 but your product shows no message | Check ActionMailbox records, job workers, failed routing jobs and your mailbox's `process` method. The default mailbox only logs receipt. |
+| Retrying creates no new inbound record | Identical MIME for the same SMTP recipient is intentionally deduplicated. |
+| Bcc message appears routed to the wrong mailbox | Use `Envelope.for(inbound_email)["to"]` after checking the envelope exists; MIME `To` does not identify every SMTP recipient. |
+| Quoted or internationalized addresses are rejected | Both v2 and v3 envelopes support ASCII dot-atom addresses, not every possible email address syntax. |
+
+## Local development
+
+Restart Rails after upgrading so the ingress-only guard is installed. Start
+Rails on the expected port before `cloudflare:email:dev`, install `cloudflared`,
+and use development credentials and a development receiving route.
+
+The tunnel only permits POSTs to the email ingress. Opening its root URL in a
+browser returning 404 is expected. When you stop the tunnel, its URL remains in
+the development Worker until the next update; it no longer reaches your app.
+
+## Saved outbox operations
+
+```sh
+bin/rails cloudflare:email:pending_deliveries
+```
+
+This lists operations requiring attention for the configured account. It does
+not dispatch or repair them automatically.
+
+| State or error | What to do |
+| --- | --- |
+| `prepared` | The message is saved and can be dispatched using its existing operation key. Check for an enqueue failure or stopped worker. |
+| `sending` | A process claimed the send. Verify its status; age alone does not prove it failed to send. |
+| `unknown` | Collect provider evidence before making a resend decision. |
+| `partial` | Review individual acceptance outcomes. Already accepted recipients must not receive a batch retry. |
+| `accepted` | Repeated delivery uses the existing record without another send. Look at recipient lifecycle for later delivery results. |
+| `rejected` | Correct the cause; a deliberate new attempt needs a new operation key. |
+| `SnapshotConflict` | The same key was used with different MIME/envelope data. Retry the saved identity; do not re-render it. |
+
+For a known `prepared` operation, dispatch the saved message with:
+
+```sh
+OPERATION_KEY='your-existing-operation-key' bin/rails cloudflare:email:deliver
+```
+
+For uncertainty, follow [audited reconciliation](outbox.md#reconcile-uncertainty).
+Never reset a row to `prepared` or delete the ledger to make a retry go through.
+Reconciliation requires an authorized operator and evidence; the gem records
+the actor you supply but does not authenticate that person.
+
+## Delivery updates
+
+| What you see | What to check next |
+| --- | --- |
+| Queue stays empty | Check the Email Sending subscription, sending domain, selected event types and a real send from that domain. |
+| A verified Routing destination received mail but Sending feedback is missing | Use optional [Routing delivery confirmation](routing-deliveries.md) with its separate read credential. Missing evidence is unresolved, not proof of failure; keep the normal recipient address. |
+| Polling fails before processing | Check the queue ID, separate Queues Read/Write token, HTTP pull configuration and configured event handler. |
+| Events process once then stop | `consume_events` is a one-batch task. Schedule it to run repeatedly. |
+| Events stay unmatched | Check account, normalized provider message ID and recipient. Schedule replay; a receipt can arrive before the send result is saved. |
+| Acknowledged event did not update the UI | Durable receipt storage and product projection are separate. Check replay, callback failures and application correlation. |
+| Old delivery status does not replace a newer one | Ordering and terminal-state guards intentionally reject stale updates. |
+| One event repeatedly fails | Inspect validation/handler errors and dead-letter queue policy. Invalid events are not acknowledged by the consumer. |
+
+```sh
+bin/rails cloudflare:email:consume_events
+bin/rails cloudflare:email:replay_events
+```
+
+See [delivery events](delivery-events.md) for queue setup and
+[observability](../README.md#observability-and-permissions) for notifications you
+can connect to your monitoring. A delivery notification wraps handler execution;
+it is not proof that queue acknowledgement completed.