cloudflare-email 0.1.0 → 0.3.0

data/docs/activerecord-tenanted.md

@@ -0,0 +1,181 @@
+# SQLite mailboxes with activerecord-tenanted
+
+Use this setup when each organization has its own SQLite database. The shared database holds receiving domains and delivery-event routing. Mailboxes, messages, and the outbox live in the organization's database.
+
+This setup is entirely opt-in. Skip this guide for a single database: installing
+the gem or running the mailbox generator does not enable database tenancy.
+
+`activerecord-tenanted` is an optional application dependency. The gem's integration test uses version 0.8 on Rails 8.1; you do not need it for a single database or another tenant adapter.
+
+## 1. Configure your databases
+
+Add `gem "activerecord-tenanted", "~> 0.8.0"` to your application's Gemfile and run `bundle install`.
+
+For example, in `config/database.yml`:
+
+```yaml
+production:
+  primary:
+    adapter: sqlite3
+    database: storage/directory.sqlite3
+    migrations_paths: db/migrate
+  tenant:
+    adapter: sqlite3
+    tenanted: true
+    database: storage/tenants/%{tenant}/db.sqlite3
+    migrations_paths: db/tenant_migrate
+```
+
+Use equivalent entries for development and test. Keep tenant keys stable, such as an organization's internal identifier. Customer-supplied hostnames are not tenant authorization.
+
+Generate the mailbox migrations in the correct directories:
+
+```sh
+bin/rails generate cloudflare:email:mailboxes \
+  --directory-migrations-path=db/migrate \
+  --tenant-migrations-path=db/tenant_migrate
+```
+
+Put Action Mailbox and Active Storage migrations in the tenant migration directory too. Apply the shared migrations and the tenant migrations using your application's database provisioning workflow. Keep every existing tenant's schema current before starting workers against a new release.
+
+## 2. Load stable connection classes before the mailbox models
+
+The optional gem models inherit from your tenant base. That base must keep the same Ruby class identity across Rails development reloads. Define it in a file you explicitly require, outside reloadable model directories. If your app already has these bases, use those same classes; do not create competing versions.
+
+For example, `lib/email_database_records.rb`:
+
+```ruby
+class TenantRecord < ActiveRecord::Base
+  self.abstract_class = true
+  tenanted "tenant"
+end
+
+class DirectoryRecord < ActiveRecord::Base
+  self.abstract_class = true
+  connects_to database: { writing: :primary }
+end
+```
+
+Keep this file outside any paths your application configures for reloadable autoloading. Require it during application initialization after `activerecord-tenanted` has installed its Active Record support, and before the generated mailbox initializer loads the optional models. Add this inside your application class in `config/application.rb`:
+
+```ruby
+config.active_record_tenanted.connection_class = "TenantRecord"
+config.active_record_tenanted.tenanted_rails_records = true
+
+config.active_record_tenanted.tenant_resolver = ->(request) do
+  if request.path == "/rails/action_mailbox/cloudflare/inbound_emails"
+    nil
+  else
+    request.subdomain # Replace with your existing authorized tenant resolver.
+  end
+end
+
+initializer "my_app.cloudflare_email_tenancy",
+    after: "active_record_tenanted.active_record_base",
+    before: :load_config_initializers do
+  require Rails.root.join("lib/email_database_records").to_s
+  require "cloudflare/email/tenancy"
+  require "cloudflare/email/mailboxes/configuration"
+
+  Cloudflare::Email::Tenancy.configure(
+    base_class: TenantRecord,
+    current: -> { TenantRecord.current_tenant },
+    switch: ->(key, &block) {
+      unless TenantRecord.tenant_exist?(key)
+        raise Cloudflare::Email::Mailboxes::Unavailable,
+          "tenant is not provisioned"
+      end
+      TenantRecord.with_tenant(key, &block)
+    }
+  )
+  Cloudflare::Email::Mailboxes.configure(directory_base: DirectoryRecord)
+end
+```
+
+Leave the generated `cloudflare_email_mailboxes.rb` initializer to require `cloudflare/email/mailboxes`. Remove any duplicate tenancy configuration from other initializers.
+
+The ingress exception in the resolver matters: `activerecord-tenanted` normally locks a request to the tenant selected from its hostname. Email ingress must select its tenant from the verified recipient and shared domain directory, after the gem verifies the complete message signature. Returning `nil` lets that signed-recipient lookup select the correct database.
+
+`tenanted_rails_records = true` puts Action Mailbox and Active Storage on the configured tenant connection. Include their tables in tenant migrations and configure private storage. The gem restores its tenant context for its supported email and attachment jobs. For your own jobs that serialize tenant model arguments, prepend `Cloudflare::Email::TenantJobContext` and enqueue them inside `Cloudflare::Email::Tenancy.with(key)`; ordinary host tenant context alone does not establish the gem's context.
+
+## 3. Provision organizations separately from mailboxes
+
+Create tenant databases in your trusted organization-provisioning workflow:
+
+```ruby
+TenantRecord.create_tenant("organization-123")
+```
+
+The switch adapter above refuses missing tenants. Receiving mail or replaying a delivery event will never create a new tenant database implicitly.
+
+After registering and activating the organization's receiving domain, use the mailbox API within its context:
+
+```ruby
+Cloudflare::Email::Mailboxes.for_tenant("organization-123") do |inboxes|
+  mailbox = inboxes.create(
+    name: "Support",
+    address: "support@customer.example.com",
+    owner_ref: "team:42"
+  )
+  # Provision and activate the address before receiving or sending mail.
+end
+```
+
+See the [mailbox guide](mailboxes.md) for domain activation, address provisioning, sending, and event replay. Your application still authorizes which organization, mailbox, and message each user can access.
+
+## Account emails without an organization
+
+Password resets and portal invitations can belong to the application rather
+than an organization. If you enabled separate tenant databases, give those
+outbox records an explicitly provisioned, host-reserved database too. Keep the
+business record's organization empty; a storage key is not an organization or
+an authorization grant.
+
+For example, after configuring the adapter above, provision and migrate a
+reserved database through your deployment workflow:
+
+```ruby
+# Run once through trusted provisioning, not during sending or event replay.
+TenantRecord.create_tenant("_system_outbound")
+```
+
+Your own service can select storage consistently for sending and feedback:
+
+```ruby
+module EmailStorage
+  SYSTEM_KEY = "_system_outbound".freeze
+
+  def self.with_outbound_storage(organization_key, &block)
+    # The caller must supply an already-authorized organization key.
+    key = organization_key.nil? ? SYSTEM_KEY : organization_key
+    Cloudflare::Email::Tenancy.with(key, &block)
+  end
+end
+
+EmailStorage.with_outbound_storage(nil) do
+  # Prepare/read/reconcile the system email's saved outbox operation here.
+end
+```
+
+Reserve the key against customer selection, include this database in migrations,
+backups and restoration drills, and use the same selection for receipt replay.
+If your shared business records use another database, retain their own durable
+receipt/projection boundary: a tenant commit and a shared commit are not atomic.
+Replay a committed gem operation rather than sending it again.
+
+Never modify the tenancy adapter to treat every missing context as the system
+database. Missing context must continue to fail closed. Your organization's job
+fan-out should enumerate real organizations, not every database file. Applications
+without configured multi-tenancy can keep ordinary system and organization mail
+in their existing single database; this recipe does not enable tenancy by default.
+
+## What is verified
+
+The optional CI job boots a real Rails application with `activerecord-tenanted`, runs the gem's tenant migrations in two SQLite databases, and checks identical numeric IDs remain isolated. It also verifies context restoration, refusal to create unknown tenant databases, and GlobalID's missing/wrong-tenant rejection. Separate integration tests exercise mailbox ingress, sending, jobs, and delivery-event replay.
+
+Run the library-specific smoke test locally with:
+
+```sh
+BUNDLE_GEMFILE=gemfiles/tenanted.gemfile bundle install
+BUNDLE_GEMFILE=gemfiles/tenanted.gemfile bundle exec ruby test/support/activerecord_tenanted.rb
+```

data/docs/architecture.md

@@ -0,0 +1,105 @@
+# Gem and inbox responsibilities
+
+The Cloudflare gem supplies email transport and reusable delivery infrastructure.
+The inbox application supplies a product built on that infrastructure. Plain Ruby
+users should not need Rails or a database. Rails users should be able to opt into
+durable infrastructure without copying the reference inbox's models and services.
+
+## Implemented in this extraction
+
+| Gem capability | Application responsibility |
+| --- | --- |
+| Optional mailbox/address directory and tenant connection adapter | Authorize domain ownership, provision tenant databases and grant user access |
+| Mailbox memberships, read/archive state and retained raw mail | Inbox UI, retention schedule and explicit purge policy |
+| Shared event intake, tenant correlation and tenant-aware jobs | Durable queue workers, scheduled recovery and schema rollout to every tenant |
+| Structured/raw sending and ActionMailer transport | Compose UI, recipients and send authorization |
+| `Response#accepted?`, plus individual recipient outcomes | Handle partial acceptance without resending accepted recipients |
+| Authenticated ingress (default v2; opt-in v3 [metadata](custom-ingress.md)) and context-scoped deduplication | Map trusted recipient to an authorized mailbox; apply sender and document policy |
+| `MessageId.normalize` and returned provider IDs | Store conversation membership and scope reply lookups |
+| Queue decoding, validation and ACK | Queue/subscription setup and recurring execution |
+| Optional ActiveRecord event receipts, deduplication and indexed replay | Configure queue polling and receipt retention |
+| Immutable outbox snapshots, send claims, per-recipient outcomes | Authorize sending and choose a stable operation key |
+| `DeliveryEvents` account/message/recipient correlation and ordering | Transactional callback to update product records |
+| Send/replay jobs, recovery tasks and audited reconciliation | Authorize operators and provide evidence of provider outcome |
+
+The ActiveRecord adapter is explicit opt-in. Its generator installs a receipt table
+and initializer; the default plain Ruby client does not load ActiveRecord. Its
+handler applies application writes on the same database connection as the receipt.
+It does not wrap HTTP calls or other external effects in a database transaction.
+
+Version 0.2 is a preproduction break: v1 ingress and signed Message-ID tokens are
+removed. Cloudflare's documented queue encodings and recipient-response forms are
+provider contracts, so accepting them is not obsolete application compatibility.
+Historical verification reports describe their dated runs, not the current API.
+
+## Implemented: durable outbound delivery
+
+The inbox now uses the gem's ledger tables and orchestration. Its model subclasses
+add application message associations and display snapshots; they do not maintain
+a second sending ledger. See the [outbox guide](outbox.md) for installation and API.
+
+1. Claim an application-supplied operation key scoped to an account using a unique
+   index before sending; repeated or concurrent calls cannot silently resend.
+2. Persist immutable rendered MIME and envelope recipients before the network
+   request. Track each recipient separately, including partial acceptance.
+3. Separate preparation failures from ambiguous outcomes. A timeout, process death
+   or persistence failure after acceptance keeps the operation blocked. An elapsed
+   timeout alone never proves the message was not sent.
+4. Persist validated provider IDs and recipient acceptance outcomes separately
+   from later lifecycle events. Replay correlates account, message and recipient;
+   conflicting IDs remain uncertain. The network and database are not atomic.
+5. Expose audited reconciliation with caller-supplied actor/reason and evidence.
+   The application authorizes the operator; the gem enforces legal transitions.
+6. Provide jobs/tasks and notifications that preserve the same claim on retries.
+   Include migration/import support for the reference inbox's existing attempts.
+
+The suite exercises concurrent senders, actual process termination, acceptance
+followed by persistence failure, partial recipients, event-before-response,
+out-of-order events, callbacks that roll back, and recovery without a duplicate
+send. PostgreSQL and SQLite run separate concurrency checks. Inbox HTTP and browser
+workflows use the shared implementation, with controlled local provider responses.
+
+Historic attempts did not preserve rendered MIME. Their import retains available
+bodies, IDs, outcomes and operator evidence and marks reconstructed snapshots.
+Unknown historical outcomes remain blocked. No migration claims to recreate the
+exact bytes of a previously sent message.
+
+## Operational completion
+
+The reference inbox supplies a functional mailbox product over these APIs. Before
+production use, configure sending DNS and receiving routes, queue subscriptions
+and dead-letter handling, durable Rails jobs, receipt/MIME retention and backups,
+and monitoring for prepared/sending/unknown/partial operations. Exercise live
+external mailbox delivery and recovery with the deployed revision. Installation
+does not automatically provision domains or deploy infrastructure.
+
+Current limitations are deliberate and visible: no provider exactly-once API,
+no automatic resend of uncertain or rejected operations, no multi-provider-ID
+operation (conflicting IDs require review). Direct inbound forwarding can reject
+mail during a Rails outage. The default [durable Worker path](../templates/worker/README.md#durable-inbound-delivery)
+commits raw mail and stable envelope context to R2 before returning successfully.
+Queue handoffs and a scheduled recovery pass retry pending mail; a Rails 2xx
+allows removal from the pending store. Queue expiration does not remove R2 mail.
+This boundary requires durable Rails persistence before 2xx, idempotent replay,
+private R2 storage without expiration of pending objects, and operational
+monitoring. It cannot guarantee acceptance when Cloudflare itself cannot store
+the incoming message.
+A prepared operation can be dispatched using its existing identity after a job
+enqueue failure; sending/unknown operations require evidence-based reconciliation.
+Notifications indicate method execution and may run inside an outer transaction;
+the durable database record is authoritative.
+
+## Keep in the inbox product
+
+Users, tenancy, mailbox ownership, conversations, folders, search and UI remain in
+the inbox. AI context, review flags, approval thresholds, auto-send policy and
+operator permissions also stay there. Suppression/unsubscribe requirements depend
+on message purpose and application policy; expose provider outcomes, but do not
+silently impose a marketing subscription model on transactional mail.
+
+The optional [mailbox module](mailboxes.md) now packages mailbox persistence and
+address management over the existing transport/receipt APIs. It includes a
+[tenant adapter](activerecord-tenanted.md), without adding a tenant library to
+the plain Ruby client. The optional [management engine](management-engine.md)
+consumes these same APIs with host-supplied authentication and authorization.
+Full inbox products can continue using them through their own frontends.

data/docs/custom-ingress.md

@@ -0,0 +1,207 @@
+# Use your existing inbound email pipeline
+
+This integration API is available in gem version 0.3.0.
+
+You can adopt mailbox registration without replacing your Worker, document processing, sender review, or archive. Use the gem to authenticate the request and resolve an accepted address, then keep your application's policy and processing.
+
+A useful starting point is one mailbox per site: an organization owns a receiving domain, a site owns a mailbox, and that mailbox can have several accepted addresses. This is an application convention, not a requirement of the gem. Database tenancy is optional; a single SQLite database works too.
+
+## Register addresses before accepting mail
+
+Follow [mailbox setup](mailboxes.md) to register and activate the receiving domain and accepted addresses. With existing catch-all Worker routing, address creation can be a database operation once an administrator has confirmed that routing covers the exact domain. Registering a domain does not create DNS records or extend wildcard coverage.
+
+Use the same provisioning service from organization/site onboarding and from the management UI. Keep a stable site reference in the mailbox's `owner_ref`; keep site permissions, slug changes, document workflows, and sender allowlists in your app. Treat a rename as an explicit alias/lifecycle decision so old addresses are not accidentally lost.
+
+For separate organization databases, configure [the SQLite tenant adapter](activerecord-tenanted.md) before loading mailbox models. The shared directory resolves the signed recipient to a tenant. Action Mailbox, Active Storage, and the gem's mailbox records must all use that tenant's connection.
+
+## Verify a custom endpoint before writing anything
+
+`Cloudflare::Email::Ingress.verify` is usable outside the bundled controller. It accepts a String or IO body, bounds the raw body size, and returns an immutable result. Successful verification exposes the exact binary body and authenticated envelope; rejected requests expose no verified message.
+
+The following controller is a starting point for a host with registered mailboxes:
+
+```ruby
+require "cloudflare/email/ingress"
+
+class InboundEmailsController < ActionController::API
+  def create
+    result = Cloudflare::Email::Ingress.verify(
+      secret: Rails.application.credentials.dig(:cloudflare, :ingress_secret),
+      headers: request.headers,
+      body: request.body,
+      content_length: request.content_length,
+      max_email_bytes: 25 * 1024 * 1024
+    )
+
+    case result.status
+    when :too_large
+      return head :payload_too_large
+    when :bad_signature, :stale
+      return head :unauthorized
+    end
+
+    verified = result.message
+
+    Cloudflare::Email::Mailboxes.receive(
+      recipient: verified.envelope.fetch("to")
+    ) do |destination|
+      # This block runs in the recipient's tenant. Apply your sender/review
+      # policy here, before persistence schedules Action Mailbox routing.
+      # Your policy may raise a host error or return nil instead of persisting.
+      # destination.owner_ref identifies your site/team; validate it using
+      # your application's policy in this tenant context.
+      verified.persist_action_mailbox!
+    end
+
+    head :ok
+  rescue Cloudflare::Email::Mailboxes::Unavailable
+    head :unprocessable_entity
+  end
+end
+```
+
+Mount this controller at your own route and point your existing Worker there. The host owns response codes and retry policy. If your policy returns nil and you acknowledge the request, you are accepting responsibility for that email: persist a durable review record or deliberately discard it according to your application's policy. A successful verification alone does not queue processing or create a mailbox.
+
+Do not use the MIME `To` header or an unauthenticated URL subdomain to select storage. `verified.envelope.fetch("to")` is the signed SMTP recipient. `Mailboxes.receive` checks that its domain, mailbox, and accepted address are active before entering the persistence block.
+
+`persist_action_mailbox!` stores the verified raw bytes and metadata in Action Mailbox. The receiving block adds mailbox membership in the same tenant transaction. Rails schedules normal routing after the transaction commits. Apply policies that must stop processing before calling persistence; a check performed after receiving returns can be too late.
+
+For an application that owns a different raw-email store, use `verified.body`, `verified.envelope`, `verified.provider_metadata`, `verified.message_checksum`, and `verified.storage_metadata` with your own persistence/transaction system. `Mailboxes.receive` specifically expects an Action Mailbox inbound email record (or nil) from its block; do not pass an unrelated processing record. The gem does not choose your archive retention, held-message model, or document queue.
+
+## Persist the email and link your business record
+
+Email persistence remains part of the gem's supported path. Action Mailbox stores
+the raw MIME using Active Storage, the verifier saves authenticated metadata, and
+`Mailboxes.receive` adds the inbox membership. Your processing/review record can
+refer to that email rather than storing a second copy of its raw content:
+
+```ruby
+Cloudflare::Email::Mailboxes.receive(
+  recipient: verified.envelope.fetch("to")
+) do |destination|
+  # Validate owner_ref and sender policy here, before any routing is scheduled.
+  inbound = verified.persist_action_mailbox!
+  if inbound
+    # Example host model, on the SAME tenant connection as the gem records.
+    EmailIntake.create!(
+      inbound_email_id: inbound.id,
+      mailbox_id: destination.mailbox_id,
+      owner_ref: destination.owner_ref
+    )
+  end
+  inbound # Return the ActionMailbox record; duplicate deliveries return nil.
+end
+```
+
+The database writes commit together. A host failure rolls back the new email,
+membership and host link and prevents the routing job from being enqueued. This
+does not make an R2 archive, another database, or external API calls transactional.
+Host exceptions propagate; only unavailable registry destinations are translated
+to `Mailboxes::Unavailable`. Existing blocks without a destination argument still
+work.
+
+Persisting through ActionMailbox schedules its normal routing after commit. Put
+your processing in that route or a deliberately coordinated job pipeline. If an
+email must be held, implement a routing policy that cannot process it before
+approval; storing it is not itself a review gate. A routing job failure also needs
+normal job retry/recovery. Receipt deduplication does not make every downstream
+business side effect idempotent.
+
+Managed mailbox membership protects raw email from ActionMailbox's normal
+automatic incineration. Archiving a mailbox message keeps its content; deliberate
+purging can remove it once no other membership references the email. Raw email
+saved without membership follows the normal ActionMailbox lifecycle. Keep host
+references, backup and R2 retention consistent with your chosen deletion policy.
+Multi-tenancy remains opt-in.
+
+## Resolve an address with your own persistence
+
+If your application already owns its raw-email store, use the standalone API:
+
+```ruby
+Cloudflare::Email::Mailboxes.with_recipient(
+  recipient: verified.envelope.fetch("to")
+) do |destination|
+  # Example host-owned persistence service; it must commit durably before ACK.
+  ExistingEmailStore.save!(
+    tenant_key: destination.tenant_key,
+    mailbox_id: destination.mailbox_id,
+    recipient: destination.recipient,
+    raw: verified.body,
+    metadata: verified.storage_metadata
+  )
+end
+```
+
+This checks the active domain, address and mailbox, enters the configured tenant,
+and yields an immutable `Destination` with `tenant_key`, `mailbox_id`, `address_id`,
+`receiving_domain_id`, `recipient` and `owner_ref`. It returns the block's result,
+creates no email or membership, starts no storage transaction, and requires no
+ActionMailbox. Configure the optional mailbox registry and tenant adapter as usual.
+
+Both APIs must be called after complete request verification. Destination values
+are routing snapshots, not authorization tokens: an owner reference does not
+prove a site still exists or that a sender may submit to it. Use records inside
+their tenant context and recheck lifecycle/permissions when later work requires
+it. Both APIs restore the previous tenant context when the block returns or raises.
+
+## Carry Worker metadata with authenticated provenance
+
+The default Worker protocol remains v2: it authenticates the raw message and SMTP envelope. Optional v3 also authenticates a bounded metadata object:
+
+```json
+{
+  "source": "cloudflare",
+  "data": {
+    "archive_key": "inbound/example.eml"
+  }
+}
+```
+
+The `archive_key` above is an illustrative application-defined value. The gem does not fetch that object or verify an archive exists. Your trusted Worker constructs the data from sources whose provenance you understand.
+
+V3 binds the encoded metadata to the timestamp, envelope, and exact raw bytes. The `X-CF-Email-Metadata` header is unpadded base64url UTF-8 JSON. Metadata attached to a v2 request is rejected rather than treated as authenticated. Existing v2 requests without metadata continue to work.
+
+The Worker template exports `signedEmailHeaders` for an existing transport and `forwardEmail` for the bundled forwarding behavior. Keep your current archive and retry handling, and use the header builder to authenticate the original raw bytes:
+
+```js
+import { signedEmailHeaders } from "./cloudflare-ingress.js";
+
+const headers = await signedEmailHeaders({
+  secret: env.INGRESS_SECRET,
+  raw, // Uint8Array from your bounded reader
+  from: message.from,
+  to: message.to,
+  metadata: { source: "cloudflare", data: { archive_key: archiveKey } },
+});
+// Send exactly raw with these headers using your existing transport.
+```
+
+Here `cloudflare-ingress.js` is your local copy of the template's `src/index.js`. `raw` and `archiveKey` come from your existing bounded reader and archive operation. See the [Worker integration instructions](../templates/worker/README.md) for supported metadata values and forwarding behavior. Upgrade the Rails receiver before enabling v3 in the Worker.
+
+In your Action Mailbox handler, read persisted metadata through the gem:
+
+```ruby
+require "cloudflare/email/provider_metadata"
+
+metadata = Cloudflare::Email::ProviderMetadata.for(inbound_email)
+archive_key = metadata&.dig("data", "archive_key")
+```
+
+This reads verified Active Storage metadata, not similarly named MIME headers. Authenticate your Worker first and preserve the verified object unchanged. Avoid adding secrets or unnecessary personal information to provider metadata.
+
+**A valid Worker signature proves that your trusted Worker submitted the request. It does not prove the original email sender is authentic.** Even metadata labelled `source: "cloudflare"` is an assertion made by the holder of the ingress secret. Do not copy sender-controlled MIME headers into a “trusted authentication” field. If your existing Worker has reliable authentication evidence, preserve its documented provenance and let your application decide how that evidence affects acceptance. The gem intentionally does not infer SPF/DMARC results or implement a sender allowlist.
+
+Retries with the same recipient, raw bytes, and metadata context reuse the inbound record. Aliases receive distinct membership context. Changing signed metadata produces a distinct checksum: stable values are preferable to per-attempt timestamps or random IDs. Keep downstream document extraction and external side effects idempotent too.
+
+## Adopt incrementally
+
+1. Inventory existing accepted addresses, organization/subdomain mappings, fallback destinations, and disabled sites. Backfill records explicitly; do not silently create a mailbox for every incoming address.
+2. Confirm existing Worker routing for one organization's exact domain and activate only verified addresses. Exercise an alias, unknown address, suspended mailbox, and cross-tenant destination with synthetic mail.
+3. Add request verification and preserve your current sender review, archive behavior, error responses, and size limits. Test that rejected or held mail cannot reach the processing queue.
+4. Connect site provisioning to the same mailbox API used by the [management engine](management-engine.md). Scope the engine through existing host authentication and authorization.
+5. Retire duplicate infrastructure only after comparing delivery and recovery behavior. Inbound adoption does not require switching your outbound provider.
+
+Keep the shared operational communications history separate from tenant-local raw emails and mailbox membership when those serve different purposes. Define who owns deletion, archive retention, deduplication, and processing status; two competing delivery ledgers make recovery harder.
+
+The gem's custom-ingress integration test exercises a custom controller against two real SQLite tenant databases, preserving binary MIME bytes and signed metadata before routing jobs run. It also verifies rejected metadata, host review, accepted-address enforcement, and retry behavior. It does not verify a deployed customer's Cloudflare DNS, Worker authentication evidence, R2 archive, or document-processing pipeline; those require that host's end-to-end tests.