cloudflare-email 0.2.0 → 0.3.0

data/docs/mailboxes.md

@@ -5,7 +5,7 @@ mail into them, track read/archive state, and send through the durable outbox.
 It works in one SQLite database or with a separate database per organization.
 It supplies models and services; your app supplies permissions and the UI.
 
-This module is available in version 0.2.0. Install `gem "cloudflare-email", "~> 0.2.0"`.
+This module is available since version 0.2.0. Install `gem "cloudflare-email", "~> 0.3.0"` for the latest features.
 
 **Database multi-tenancy is off by default.** The mailbox generator works with
 one ordinary database. Calling `for_tenant` groups and scopes mailbox records;
@@ -34,7 +34,8 @@ require "cloudflare/email/mailboxes"
 Loading this module enables mailbox lookup on the gem's Cloudflare ingress.
 Existing receiving addresses must be registered and activated before switching
 an existing application over. Unregistered or suspended destinations return
-HTTP 422 and the Worker rejects the delivery; there is no default-mailbox fallback.
+HTTP 422 and the Worker rejects the delivery by default. You can explicitly
+configure a domain catch-all below when your application needs that behavior.
 
 For separate organization databases, follow the
 [activerecord-tenanted setup](activerecord-tenanted.md) **before loading the
@@ -146,6 +147,67 @@ are explicit: the module does not automatically strip `+tags` or invent address
 fallbacks. Reserve application-specific names such as Rebulk's `tracking` in
 your mailbox-management policy before creation.
 
+## Receive unregistered local parts with an optional catch-all
+
+Catch-all receiving is **off by default** and is available in the 0.3
+version. It lets one existing address receive otherwise unregistered addresses
+on its exact domain, without creating an alias row for each incoming local part.
+For example, `anything@acme.example.com` can arrive in an existing support mailbox.
+It does not cover subdomains such as `anything@other.acme.example.com`.
+
+Fresh installations include the schema. For an existing installation, generate
+the optional upgrade and apply it to the database containing your mailbox tables:
+
+```sh
+bin/rails generate cloudflare:email:mailboxes:catch_all
+bin/rails db:migrate
+```
+
+With separate tenant databases, pass
+`--tenant-migrations-path=db/tenant_migrate` and run your application's tenant
+migration command for every affected tenant. Updating the gem alone keeps older
+schemas working with exact-address routing. Enabling a catch-all without its
+migration raises a configuration error.
+
+First configure and verify the domain's catch-all Email Routing rule in Cloudflare
+to send mail to your Worker. Then use your authorized provisioning code:
+
+```ruby
+Cloudflare::Email::Mailboxes.for_tenant("organization-123") do |account|
+  mailbox = account.mailboxes.find_by!(owner_ref: "team:42")
+  address = account.addresses(mailbox.id).find_by!(address: "support@acme.example.com")
+  account.enable_catch_all(address.id,
+    evidence: "Domain catch-all Worker route verified in setup ticket 57")
+
+  # Later, stop accepting unregistered local parts:
+  # account.disable_catch_all(address.id)
+end
+```
+
+The address, mailbox and receiving domain must be active before enabling it.
+The evidence is an operator assertion, as with ordinary address activation;
+this call does not change Cloudflare rules. Only one active address per domain
+can serve as a catch-all. A database constraint also protects concurrent changes.
+Suspending that address pauses fallback. If another catch-all is enabled while
+it is suspended, disable the old flag before reactivating the old address.
+
+Exact registered addresses always take precedence. An exact address that is
+pending, suspended, or belongs to a suspended mailbox is rejected; it does not
+fall through to another mailbox. The catch-all also stops receiving when its
+mailbox or domain is suspended.
+
+Both `with_recipient` and `receive` yield `destination.catch_all == true` only
+when fallback was used. `destination.recipient` remains the actual envelope
+recipient, while `address_id` identifies the existing backing address. Stored
+mailbox membership retains that actual recipient too. Apps can use this flag to
+enforce additional rules, such as allowing fallback only while an organization
+has one site, before accepting/persisting the message.
+
+Catch-all receiving grants **no additional sending addresses**. Outbound From,
+Sender and envelope sender must still match an exact active registered address.
+Disable catch-all receiving through the API; the management UI displays its
+configuration but does not enable or disable it.
+
 ## Read incoming mail
 
 The Worker signs the SMTP recipient. Rails verifies the whole request, resolves
@@ -294,6 +356,8 @@ lookup. Drain existing ActionMailbox/ActiveStorage queues before enabling this
 mode: previously serialized jobs without the new metadata are rejected.
 
 The gem does not create organizations/users, verify customer domain ownership,
-provide IMAP/POP, or supply an inbox UI. The original Rebulk document-processing
+provide IMAP/POP, or supply a full compose/conversation inbox. The optional
+[management engine](management-engine.md) supplies mailbox administration and
+plain-text previews using your host's access policy. The original Rebulk document-processing
 Worker contract and sender-review policy still need a separate application
 migration; installing this module does not replace that live pipeline.

data/docs/management-engine.md

@@ -0,0 +1,190 @@
+# Optional mailbox management engine
+
+The management engine is a small, server-rendered Rails interface for the
+[managed mailbox APIs](mailboxes.md). It works with ordinary Rails apps and with
+apps using Inertia, React, Turbo or another frontend. No JavaScript, Node build,
+asset pipeline or frontend package is required for the engine.
+
+This feature is available in RubyGems 0.3.0.
+
+## What you get
+
+- Mailbox lists, names, creation and aliases on allowed receiving domains.
+- Address setup status and mailbox suspension/resumption.
+- A paginated list of received messages and an escaped plain-text preview.
+- Optional read/unread and archive/unarchive controls.
+- Ordinary CSRF-protected forms, mobile layouts and bundled CSS.
+
+Your app supplies login, permissions, domain entitlements and any organization
+mapping. The engine does not create users, claim domains, edit DNS, provision
+Cloudflare routes, send mail, or permanently delete records. The default creation
+hooks create pending addresses. Your administrator or existing provisioning code
+completes routing and activation through the same Ruby APIs.
+
+The viewer never renders sender HTML, loads remote images, or provides raw MIME
+or attachment downloads. It shows attachment names and up to 100,000 plain-text
+characters. Compose, conversations, AI workflows and product search belong in
+your application.
+
+## Install and mount
+
+First install the managed mailbox tables and enable the module using
+[the mailbox setup guide](mailboxes.md). SQLite works; database tenancy remains
+off unless your app configures it explicitly.
+
+Require the engine **before Rails initializes**, after Bundler loads the gem:
+
+```ruby
+# config/application.rb, after Bundler.require(*Rails.groups)
+require "cloudflare/email/management"
+```
+
+Configure a host adapter in an initializer:
+
+```ruby
+# config/initializers/cloudflare_email_management.rb
+Cloudflare::Email::Management.configure do |config|
+  # Resolve the class when handling the request, so Rails reloading works.
+  config.adapter = ->(controller) { EmailManagementAccess.new(controller) }
+  config.back_path = ->(controller) { controller.main_app.root_path }
+end
+```
+
+Mount it wherever it fits your application:
+
+```ruby
+# config/routes.rb
+mount Cloudflare::Email::Management::Engine => "/email-management",
+  as: :email_management
+```
+
+Installing the gem does not expose this interface automatically. Without a
+configured adapter and enabled mailbox module the mounted interface returns 503.
+The base adapter grants no access. Its public stylesheet endpoint serves only
+the bundled CSS.
+
+## Connect your authentication and ownership
+
+Here is a single-database example using Rails' generated authentication convention
+(`Session`, `Current.session`, and a signed `session_id` cookie). Match the cookie
+and session lookup to your app; the agentic inbox example uses `session_token`.
+Use the host authentication system's expiry, revocation and access policy.
+
+```ruby
+# app/services/email_management_access.rb
+class EmailManagementAccess < Cloudflare::Email::Management::Adapter
+  ACTIONS = %i[index show create add_address suspend resume
+    show_message mark_read archive].freeze
+
+  def authenticate!
+    Current.session = Session.find_by(
+      id: controller.request.cookie_jar.signed[:session_id]
+    )
+    @user = Current.user
+    return true if @user
+
+    controller.redirect_to controller.main_app.new_session_path
+    false
+  end
+
+  def tenant_key = "application"
+  def owner_ref = "User:#{@user.id}"
+
+  def mailboxes(session)
+    session.mailboxes.where(owner_ref: owner_ref)
+  end
+
+  def allowed?(action, mailbox = nil)
+    @user.present? && ACTIONS.include?(action) &&
+      (mailbox.nil? || mailbox.owner_ref == owner_ref)
+  end
+
+  def domains(_session)
+    ["in.example.com"] # Only domains this user is entitled to use.
+  end
+
+  def create_mailbox(session, name:, address:)
+    session.create(name: name, address: address, owner_ref: owner_ref)
+  end
+end
+```
+
+For Devise, the authentication hook can use your configured Warden scope instead
+of the cookie lookup, for example
+`@user = controller.request.env["warden"]&.authenticate(scope: :user)`.
+The engine inherits from `ActionController::Base`; host `ApplicationController`
+callbacks and methods are not inherited. Make authentication explicit in the
+adapter and return exactly `true` on success, or redirect to the host's login.
+
+The directory must already contain the active receiving domain assigned to the
+same registry key. The engine intersects `domains` with that directory and
+intersects the host mailbox relation with the current gem tenant. Parameters
+cannot select an owner or tenant.
+
+Do not return every domain merely because it exists in the database. A customer
+app should apply organization entitlement, reserved-name and signup policies.
+For separate tenant databases, return a trusted host-resolved key from
+`tenant_key` and configure the existing gem tenancy adapter and framework
+connections before mailbox models load.
+
+## Customize behavior without forking the pages
+
+The adapter has these hooks:
+
+| Hook | Contract |
+| --- | --- |
+| `authenticate!` | Authenticate the request; return exactly true or redirect/deny. |
+| `tenant_key` | Trusted registry key; never use an unchecked request parameter. |
+| `mailboxes(session)` | ActiveRecord relation containing mailboxes accessible to this principal. |
+| `allowed?(action, mailbox = nil)` | Return exactly true to permit an action. |
+| `domains(session)` | Array of domain strings permitted for this principal. |
+| `create_mailbox(session, name:, address:)` | Return the created gem mailbox, visible in the host's scope. |
+| `add_address(session, mailbox, address:)` | Add an address through your existing app provisioning service if needed. |
+
+The adapter factory, authentication and tenant-key resolution run before the
+mailbox context is entered; the host must establish any context its authentication
+needs. Mailbox/domain scopes, permissions and mutation hooks run inside the
+resolved mailbox context. Creation also runs in a
+database transaction; a returned mailbox outside the host scope rolls back.
+Keep network work out of creation hooks and enqueue provisioning after commit.
+The default alias hook calls `session.add_address`.
+
+Return false for `:create` or lifecycle actions to provide a restricted dashboard.
+Use `:show_message` to control message access independently of metadata. Deny
+`:mark_read` and `:archive` when the host product already owns a different
+conversation-level read/folder model. Hidden controls also reject direct requests.
+
+An application with its own mailbox record can override creation and alias hooks
+to call that application's service and return the linked gem model. The agentic
+inbox example does this: both UIs and automatic account provisioning share one
+service, so engine-created mailboxes also appear in its full inbox.
+
+## Inertia, React and Turbo applications
+
+Use a normal HTML link or full-page navigation to the mount. For example:
+
+```jsx
+<a href="/email-management">Manage mailboxes</a>
+```
+
+The engine returns HTML, not Inertia responses. Its separate layout keeps host
+frontend dependencies out of the gem. The optional `back_path` callback returns
+a local absolute path for a Back to app link. Programmatic provisioning continues
+to work whether this engine is mounted or not.
+
+## Operational behavior
+
+Suspension preserves mailbox records and retained mail while disabling mailbox
+sending/receiving. Resuming does not activate pending addresses or repair DNS.
+Read/archive state belongs to the gem mailbox memberships and does not implicitly
+rewrite host conversation records.
+
+Private pages use no-store caching, a restrictive CSP and a same-origin referrer
+policy. Forms check both Rails CSRF tokens and origins. Serve the host over HTTPS,
+configure trusted proxy headers correctly, and keep its session cookies secure.
+Do not disable CSRF to work around a proxy configuration issue.
+
+Verification includes real Rails sessions, owner/tenant scoping, all operation
+permissions, CSRF/origin checks, rollback, escaped previews, retained raw source,
+and eager-loading a core-only app without exposing the engine. The example also
+tests desktop/mobile Chromium and JavaScript-disabled forms with synthetic mail.

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/troubleshooting.md

@@ -30,15 +30,15 @@ FROM=hello@mail.example.com TO=you@example.net bin/rails cloudflare:email:send_t
 | --- | --- |
 | 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 that Rails and Worker both use the v2 code. Upgrade both together. |
+| 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. Its upstream request limit is 15 seconds; there is no durable inbound buffer. |
+| 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 | The v2 envelope currently supports ASCII dot-atom addresses, not every possible email address syntax. |
+| Quoted or internationalized addresses are rejected | Both v2 and v3 envelopes support ASCII dot-atom addresses, not every possible email address syntax. |
 
 ## Local development
 
@@ -85,6 +85,7 @@ the actor you supply but does not authenticate that person.
 | 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. |

data/docs/upgrading-0.2.md

@@ -26,6 +26,11 @@ Pause test ingress while updating Rails and the deployed Worker together; verify
 the matching ingress URL and shared secret before resuming delivery. There is no
 legacy routing mode or supported mixed-version rollout.
 
+The 0.3 custom-ingress additions preserve v2 as the default and add
+opt-in v3 for authenticated Worker metadata. That additive upgrade is separate
+from the v1-to-v2 break above: upgrade the Rails receiver before enabling v3 in
+your custom Worker. See [custom ingestion](custom-ingress.md).
+
 Rails stores authenticated metadata before enqueueing routing jobs.
 `Cloudflare::Email::Envelope.for(inbound_email)` returns a string-keyed `from`/`to`
 hash for accepted ingress. It returns `nil` for records from another ingress or

data/docs/upgrading-0.3.md

@@ -0,0 +1,55 @@
+# Upgrade from 0.2 to 0.3
+
+Update your Gemfile to `gem "cloudflare-email", "~> 0.3.0"`, run
+`bundle update cloudflare-email`, and deploy Rails first. Updating the gem does
+not replace your deployed Worker, change DNS, or enable optional mailbox features.
+If you are upgrading from 0.1, complete the [0.2 upgrade](upgrading-0.2.md) too.
+
+## Receiving mail while Rails is down
+
+New installations can use the [Deploy to Cloudflare template](../templates/deploy-to-cloudflare/README.md)
+to provision the Worker resources through Cloudflare's setup form. Existing
+installations should preserve their resources and pending mail using the steps below.
+
+The bundled Worker now stores inbound mail in private R2 before accepting it,
+then delivers through a Queue with scheduled recovery. Before deploying it:
+
+1. Create an R2 bucket and Queue for each environment.
+2. Configure the `INBOUND_EMAIL_STORE` binding, `INBOUND_EMAIL_QUEUE` producer
+   and consumer, and once-per-minute cron from the bundled `wrangler.toml`.
+3. Preserve your ingress URL and shared secret. Deploy with Wrangler first;
+   the Rails deploy task does not provision infrastructure.
+4. Verify that mail queues during a Rails outage, drains after recovery, and
+   retries without duplicating application records. Monitor pending mail and age.
+
+Follow the [durable delivery guide](../templates/worker/docs/durable-inbound.md)
+for commands, retention requirements, capacity limits, and recovery behavior.
+Missing infrastructure fails visibly. To deliberately retain single-attempt
+delivery, explicitly select `INBOUND_DELIVERY_MODE=direct` before deploying.
+Direct mode cannot buffer outages. Keep existing bindings and cron so previously
+stored mail continues to drain. The old `DURABLE_INBOUND_ENABLED` flag is removed.
+
+Messages without a parseable Message-ID now receive a deterministic fallback
+across Rails hosts. Historical records created with the old hostname-dependent
+fallback may duplicate on replay; reconcile old archives before replaying them.
+Retain deduplication records for your recovery horizon and make app processing
+idempotent. Durable transport is not an exactly-once delivery guarantee.
+
+## Optional features
+
+- [Management engine](management-engine.md): mount a server-rendered mailbox UI
+  with host authentication, scopes, and permissions. It is not mounted automatically.
+- [Mailboxes](mailboxes.md): enable domain catch-all explicitly on an existing
+  active address. Follow the catch-all schema upgrade instructions; exact
+  registered addresses still take precedence, and sending remains exact-address only.
+- [Custom ingestion](custom-ingress.md): integrate verified envelopes and raw
+  persistence into an existing app. Deploy Rails before enabling v3 metadata
+  signatures in a custom Worker; ordinary v2 forwarding remains supported.
+- [Routing delivery confirmation](routing-deliveries.md): configure separate
+  analytics credentials and durable receipts if needed. API acceptance alone
+  is not proof of delivery, and ambiguous evidence must not trigger a resend.
+
+Database tenancy remains opt-in. Existing tenant-enabled applications can now
+preload their schemas without selecting a tenant; actual mailbox access still
+requires explicit tenant context. No new database tables are required merely to
+upgrade the gem or use the durable inbound Worker.

data/docs/verification/2026-09-11-custom-ingress.md

@@ -0,0 +1,49 @@
+# Custom ingress and routing diagnostics verification
+
+Scope: upstream gem integration tools informed by Rebulk's existing ingestion
+pipeline. This report covers local synthetic verification, not a Rebulk rollout.
+
+## Results
+
+| Check | Result |
+| --- | --- |
+| Full Ruby suite, Ruby 3.4.1 / Rails 7.2, 8.0, 8.1 | Each: 257 tests, 916 assertions, no failures/errors/skips |
+| Shared ingress unit tests | 12 tests, 98 assertions; independent Node/Ruby v3 binary/Unicode vector, tampering, metadata bounds, short streams, immutable results, retry identity |
+| Custom Rails endpoint | 5 integration tests, 37 assertions; separate SQLite tenant databases, policy before persistence, durable signed metadata and retries |
+| Built-in Rails endpoint | V3 persistence before routing enqueue, binary preservation, retries and unsigned v2 metadata rejection; covered in the full suite |
+| Read-only routing diagnostics | 27 tests, 50 assertions; mocked Cloudflare configuration, exact-domain DNS, rule selection, ambiguous/inaccessible responses and pagination |
+| Worker | 45 tests pass; Wrangler dry-run succeeds |
+| Packaged consumer | Isolated plain Ruby install and packaged Rails installation/ingress fixtures pass |
+| Local workerd → Rails | Real local forwarding, Bcc routing, attachment preservation, wrong/missing secrets, redirects and timeout handling pass |
+
+Independent reviews found two verifier issues: a readable stream can return
+short chunks, and HMAC must use the timestamp's exact transmitted bytes. Both
+were corrected and covered by regression tests. Freshness still parses decimal
+seconds; existing bundled Worker timestamps are unchanged.
+
+## Reproduce
+
+```sh
+BUNDLE_GEMFILE=gemfiles/rails_7_2.gemfile bundle exec rake test
+BUNDLE_GEMFILE=gemfiles/rails_8_0.gemfile bundle exec rake test
+BUNDLE_GEMFILE=gemfiles/rails_8_1.gemfile bundle exec rake test
+bundle exec ruby script/verify_package.rb
+BUNDLE_GEMFILE=gemfiles/local_ingress.gemfile bundle exec ruby script/verify_local_ingress.rb
+npm --prefix templates/worker test
+npm --prefix templates/worker run check
+```
+
+Use Node 22 for the Worker and local forwarding checks.
+
+## Limits
+
+No Rebulk application code, live DNS, Worker deployment, inbox activation, R2
+archive, or gem publication was changed. The local workerd test exercises the
+default v2 transport; opt-in v3 is covered by Worker tests, an independent shared
+signature vector, and real Rails integration tests, not deployed Cloudflare mail.
+
+Routing diagnostics inspect provider configuration through mocked API tests.
+A passing configuration snapshot does not establish public DNS propagation,
+complete SPF evaluation, Worker application behavior, or live delivery. Signed
+metadata authenticates the forwarding integration's assertions; the host still
+owns original-sender trust, held-message policy, and business processing.

data/docs/verification/2026-09-12-destination-context.md

@@ -0,0 +1,46 @@
+# Destination context and email persistence verification
+
+Scope: standalone accepted-address resolution and destination context yielded
+from the existing persisted receive path. No Rebulk deployment or gem release.
+
+## Results
+
+- Full suites on Ruby 3.4.1 with Rails 7.2, 8.0 and 8.1: each passed with
+  257 top-level tests and 916 assertions. These include subprocess integration
+  fixtures whose internal assertions are not included in that top-level count.
+- The standalone service fixture uses two real SQLite tenant databases with
+  colliding mailbox IDs and no ActionMailbox loaded. It verifies host-owned
+  binary-email persistence, immutable destinations, aliases, inactive records,
+  nested context restoration, host exceptions and missing-tenant refusal without
+  creating a database. Lookup itself creates no mailbox membership.
+- The custom Rails ingress fixture verifies saved raw MIME and signed metadata,
+  mailbox membership, and a host business link created from the destination.
+  Routing jobs execute in the correct tenant after commit. Retries do not
+  duplicate the linked records. A host write failure rolls back the email and
+  membership and schedules no routing job.
+- Existing callbacks remain supported, including strict zero-argument lambdas.
+- Packaged plain Ruby and Rails consumer checks pass, including mailbox ingress,
+  routing and existing retention behavior.
+- Independent review found no remaining blockers. A callback arity compatibility
+  issue was fixed and covered before completion.
+
+## Reproduce
+
+```sh
+BUNDLE_GEMFILE=gemfiles/rails_7_2.gemfile bundle exec rake test
+BUNDLE_GEMFILE=gemfiles/rails_8_0.gemfile bundle exec rake test
+BUNDLE_GEMFILE=gemfiles/rails_8_1.gemfile bundle exec rake test
+bundle exec ruby script/verify_package.rb
+```
+
+## Boundaries
+
+Destination context is a lifecycle snapshot, not host authorization or a durable
+processing claim. Applications still validate owners and sender policy and make
+downstream work idempotent. The host owns custom-store transactions; `receive`
+preserves the existing shared tenant transaction for ActionMailbox persistence.
+Neither API makes cross-database or external object-store operations atomic.
+
+Managed mailbox memberships protect raw email from automatic incineration;
+deliberate purge, backups and host-reference cleanup remain application policy.
+These local tests do not verify Rebulk's actual queues, sender policy or archive.