cloudflare-email 0.2.0 → 0.4.0

data/docs/custom-ingress.md

@@ -0,0 +1,211 @@
+# 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
+
+    # If no custom acceptance/processing record is needed, this is sufficient:
+    # verified.receive_into_mailbox!
+    # It also repairs missing membership on duplicate delivery without rerouting.
+
+    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!` delegates verified raw bytes and metadata to the core's Rails persistence bridge. It preserves the existing new-record-or-`nil` return convention; the block example therefore does no new work for a duplicate. The default `receive_into_mailbox!` bridge also attaches the existing record, repairing a missing membership without reprocessing. Rails schedules normal routing only for newly created records 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.

data/docs/delivery-events.md

@@ -2,6 +2,15 @@
 
 Cloudflare Email Sending can publish outbound lifecycle events to Queues. This is separate from inbound Email Routing and the ActionMailbox ingress.
 
+Mail to a verified Email Routing destination can travel through Routing without
+producing an Email Sending callback. Keep using the recipient's normal address;
+do not interpret a missing callback as failure or resend the message. The optional
+[Routing delivery confirmation](routing-deliveries.md) integration checks
+authenticated analytics for qualifying single-recipient deliveries. It requires
+a separate **Analytics Read + Zone Read** credential and leaves unsupported or
+ambiguous evidence unresolved. Acceptance, receiving-server delivery and a human
+reading the message are different facts.
+
 ## Provision once
 
 1. Create a dedicated Cloudflare Queue for your application's sending events.

data/docs/features.md

@@ -5,7 +5,7 @@ services. You can use just the sending client, add incoming mail, or build a
 mailbox on top of the optional database-backed delivery tools.
 
 Start with [Getting started](getting-started.md) for working examples. These
-features are available in **0.2.0**. Database multi-tenancy is **off by default**:
+features are available in **0.4.0**, which includes **Mailbox Kit 0.1.0**. Database multi-tenancy is **off by default**:
 the optional mailbox module works in one database unless you explicitly configure
 a tenant connection adapter. A mailbox tenant key alone does not switch databases.
 
@@ -29,6 +29,34 @@ a tenant connection adapter. A mailbox tenant key alone does not switch database
 | Observe email processing | ActiveSupport notifications + `doctor` | Send/ingress/event/outbox instrumentation and configuration diagnostics |
 | Deploy receiving infrastructure | Ruby deployer and routing tasks | Environment-specific Workers, ingress secrets, address routes and DNS preflight checks |
 
+## Integration tools
+
+[Durable inbound delivery](../templates/worker/README.md#durable-inbound-delivery)
+saves raw email and its envelope in R2 before the Worker returns successfully.
+Queues attempt the Rails handoff, and a scheduled pass recovers retained mail
+after enqueue failures or retry exhaustion. Provision the storage, queue and
+schedule before deploying; direct forwarding requires an explicit fallback setting.
+
+[Routing delivery confirmation](routing-deliveries.md) adds a read-only provider
+client and optional durable receipts for qualifying single-recipient deliveries
+that appear in Routing analytics. It does not infer outcomes from missing events
+or change whether an accepted email may be sent again.
+
+Existing ingestion pipelines can use [custom ingress](custom-ingress.md) to
+verify bounded raw messages before tenant lookup, keep their own storage, or
+persist through ActionMailbox. Optional v3 signatures authenticate custom Worker
+metadata; your application still decides whether its provenance and sender policy
+are acceptable. The bundled Worker continues to use v2 by default.
+
+`Mailboxes.receive` yields the resolved destination while retaining email and
+membership persistence, so your own processing record can link to the saved mail.
+`Mailboxes.with_recipient` offers the same destination context for applications
+that own their storage. Neither replaces your sender policy or business workflow.
+
+[Read-only routing diagnostics](routing-diagnostics.md) inspect exact-domain DNS
+and the selected Worker route. They distinguish missing configuration from an
+incomplete inspection; a passing snapshot does not prove live email delivery.
+
 ## SQLite works
 
 The optional receipt and outbox tables work with **SQLite**. Keep your existing
@@ -58,7 +86,7 @@ subscriptions. The [getting-started guide](getting-started.md) walks through eac
 
 ## Protections included
 
-Incoming requests use v2 HMAC signatures covering the timestamp, SMTP sender,
+By default, incoming requests use v2 HMAC signatures covering the timestamp, SMTP sender,
 SMTP recipient and raw message. Rails checks a five-minute timestamp window.
 Identical MIME retried for the same recipient is deduplicated; delivery to a
 different recipient is stored separately.
@@ -83,7 +111,9 @@ See [managed mailbox setup](mailboxes.md) for the application-facing API and
 The gem supplies email infrastructure and optional managed mailbox records.
 Your app supplies users, mailbox permissions, conversation records, custom folders, search, compose screens,
 drafts and any AI review or approval workflow. It also decides unsubscribe and
-recipient eligibility policy. The gem does not supply an inbox UI or AI agent.
+recipient eligibility policy. The optional [management engine](management-engine.md)
+adds server-rendered mailbox administration and plain-text message previews.
+It does not supply a compose/conversation product or AI agent.
 
 An authenticated SMTP envelope tells your app which address Cloudflare received
 the message for. It does not prove the human sender's identity. Reply correlation
@@ -91,8 +121,9 @@ also does not authorize access to a conversation. Apply your app's permissions
 before displaying mail or sending a reply.
 
 You configure Cloudflare domains/DNS, queue subscriptions, durable jobs,
-monitoring, storage protection and retention. Inbound mail is not durably
-buffered by the Worker during a Rails outage. See [architecture](architecture.md)
+monitoring, storage protection and retention. Direct forwarding does not buffer
+Rails outages; the optional durable inbound setup retains pending mail in R2.
+See [architecture](architecture.md)
 for the full boundary and [security guidance](../SECURITY.md) for deployment.
 
 ## Where to go next

data/docs/getting-started.md

@@ -18,11 +18,12 @@ not need to be the same domain as your Rails application's web address.
 
 ### Install the current code
 
-Add version 0.2 to your app's `Gemfile`. If upgrading from 0.1, read the
-[upgrade guide](upgrading-0.2.md) before changing an existing Worker deployment:
+Add version 0.4 to your app's `Gemfile`. Existing mailbox installations should read
+the [core upgrade guide](../mailbox-kit/docs/upgrading.md). When upgrading from 0.2,
+also read the [Worker upgrade guide](upgrading-0.3.md):
 
 ```ruby
-gem "cloudflare-email", "~> 0.2.0"
+gem "cloudflare-email", "~> 0.4.0"
 ```
 
 ```sh
@@ -123,8 +124,18 @@ In Cloudflare **Email Routing → your apex domain → Settings → Subdomains**
 your receiving subdomain, such as `in.example.com`, and finish its DNS setup.
 This is separate from verifying the sending domain.
 
-Deploy Rails with ActionMailbox storage and workers configured. Then run these
-commands in an environment with production configuration and deployment credentials:
+Deploy Rails with ActionMailbox storage and workers configured. For guided
+Worker setup, use the [Deploy to Cloudflare template](../templates/deploy-to-cloudflare/README.md).
+It provisions R2 and Queues and prompts for your Rails URL and shared secret.
+Then select that Worker in your Email Routing rule as described in its guide.
+
+For the CLI setup instead, run these commands in an environment with production
+configuration and deployment credentials:
+
+First create the private R2 bucket and Queue, then deploy the generated Wrangler
+configuration using the [durable setup guide](../templates/worker/docs/durable-inbound.md).
+The Ruby task below updates that provisioned Worker while preserving its bindings.
+It refuses a missing bucket/queue binding or recovery schedule before changing code.
 
 ```sh
 RAILS_ENV=production bin/rails cloudflare:email:deploy_worker URL=https://app.example.com/rails/action_mailbox/cloudflare/inbound_emails
@@ -166,11 +177,11 @@ Install `cloudflared`, configure development credentials and a separate developm
 receiving route, then start Rails. In another terminal:
 
 ```sh
-bin/rails cloudflare:email:deploy_worker
+INBOUND_DELIVERY_MODE=direct bin/rails cloudflare:email:deploy_worker
 bin/rails cloudflare:email:dev
 ```
 
-The first command creates the development Worker; the second points it at a
+The first command creates the development Worker with the explicit direct fallback; the second points it at a
 temporary tunnel to your local Rails server on port 3000. Keep the tunnel running
 while testing and stop it with Ctrl-C. Set `PORT=...` if Rails uses another port.
 The task checks that Rails has the ingress-only guard; restart Rails if asked.
@@ -295,4 +306,4 @@ override it. Cloudflare has separate [outgoing size and recipient limits](https:
 
 Use [troubleshooting](troubleshooting.md) when something does not arrive,
 [the feature overview](features.md) to explore more, and
-[the upgrade guide](upgrading-0.2.md) for an existing 0.1 installation.
+[the upgrade guide](upgrading-0.3.md) for an existing 0.1 installation.

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.4.0"` for the latest features, including the provider-neutral Mailbox Kit core.
 
 **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
@@ -44,6 +45,13 @@ use the same tenant connection as the mailbox tables for atomic incoming storage
 
 ## Register an organization's domain
 
+For addresses such as `invoices@acme.in.example.com`, follow the
+[Cloudflare domain setup guide](../templates/worker/docs/domain-setup.md).
+It covers Rebulk's existing wildcard receiving pattern, one-time infrastructure
+verification, and exact organization-domain registration in Rails. The gem does
+not require a per-organization Worker allowlist or Cloudflare approval once that
+receiving infrastructure is established; new accounts must verify the provider behavior.
+
 Run directory management from your authorized administration/provisioning code.
 Do not expose arbitrary domain claims to customers without ownership checks.
 
@@ -146,6 +154,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 +363,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.