cloudflare-email 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5188438b941345c4164baca6ab1400e2fc74259c5fdd209a6d2ed9ac618147b5
-  data.tar.gz: 5e3a6ff25c460c0a73ffb3fdf44dcc62f87679f4278e328c605291d62de35fa9
+  metadata.gz: b8b7e8e8e9c8f102cf640de5aa577092947f829853daea59463263b8729ede21
+  data.tar.gz: 7303add7cb750e309c338132e114ecd40340bf5e9ee39b6b03c3f28acd9887d1
 SHA512:
-  metadata.gz: 77fe9d9c571311065e9d10d00e2c021156113ff63dec5a970f63456a6cee9d3413bfe157dcfd8e37992e5b747e1ab957d342bfc01a399d41e2c3838462067aa3
-  data.tar.gz: bf580baaec84aa3dc8894f0fbc9b770ca4fe2521a1534b248fe75bd67812a40adaf4538d321a7740b911b1fc42b80e5fd468418c4d804d635f5496710591add6
+  metadata.gz: 77cbd0de1b51f621f834fa9493c31865cc0017e0f221885503ad6c891f783f39b3e0eaf07eaabb148a9e34c694bed9d8e4a0dfa27cd052e70e0d9e17164e9483
+  data.tar.gz: 3e3ee8aa24120e3b264efd7328b18dc3c48ab044656c0e15d0f73a13d2fd18e06247ab7392bc72aba472d37bee1b080a77113e492d4dcbe8c6945e2c5ceeb34a

data/CHANGELOG.md

@@ -1,5 +1,81 @@
 # Changelog
 
+## 0.3.0 — 2026-09-13
+
+See [upgrading from 0.2](docs/upgrading-0.3.md) before deploying the updated Worker.
+
+- Add a standalone Deploy to Cloudflare template with R2/Queue provisioning,
+  secret prompts, scheduled recovery, and logs. CI checks runtime/configuration
+  synchronization with the gem's Worker and tests an isolated template copy.
+
+- Make durable inbound delivery the Worker default, with explicit direct fallback: commit original mail and envelope context
+  to R2 before Worker acceptance, deliver queue pointers with fresh signatures,
+  and recover pending mail through a bounded scheduled sweep. Rails errors,
+  lost responses, enqueue failures and exhausted queue retries retain pending
+  mail. Provisioning, protected storage and monitoring remain explicit.
+- Make missing Message-ID fallback deterministic across Rails hosts so replay
+  after a deployment does not create another inbound record. Original MIME and
+  parseable provider Message-IDs remain unchanged.
+- Add optional authenticated Routing analytics delivery confirmation with
+  encrypted immutable receipts, strict single-envelope-recipient correlation,
+  replay and transactional callbacks. Sending acceptance remains unchanged;
+  missing or ambiguous evidence never authorizes a resend.
+- Bound shared sending/queue HTTP responses by streamed bytes and a total
+  per-attempt deadline; disable implicit HTTP retries and sanitize transport
+  failures. Sending and queue acknowledgement ambiguity stays safe to replay
+  through durable receipts rather than resending accepted email.
+- Document verified Routing destinations, separate analytics credentials and
+  explicit system-mail storage with optional SQLite tenancy.
+
+- Add optional domain catch-all receiving on an existing active mailbox address,
+  with explicit verification evidence and a unique active catch-all constraint.
+  Exact registered addresses always win, including rejected inactive addresses;
+  unknown local parts retain their actual envelope recipient without new aliases.
+  Destination snapshots identify fallback, while sending stays exact-address only.
+  A separate generator upgrades existing mailbox schemas; catch-all is never
+  enabled automatically.
+
+- Allow production Rails schema preloading to boot without a selected tenant.
+  Tenant model pool access still fails closed with
+  `Cloudflare::Email::ActiveRecord::TenantConnectionUnavailable`, an
+  `ActiveRecord::ConnectionNotEstablished` error retaining the original
+  `ConfigurationError` as its cause. No default tenant is selected.
+
+- Add a reusable Worker `relayEmail` pipeline with host backend/header policies,
+  bounded raw reads, optional fail-open archive hooks, safe HTTP outcomes and
+  deadlines. `archiveEmail` writes raw bytes and envelope metadata to an optional
+  R2 bucket. Default and custom forwarding share the same HTTP transport.
+- Keep provider authentication interpretation, archive keys, retry decisions and
+  fallback destinations with the host; existing default v2/v3 forwarding remains
+  compatible. Archive deadlines bound waiting but cannot cancel an in-flight write.
+
+- Add `Mailboxes.with_recipient` for active-address resolution and immutable
+  destination context with host-owned persistence, without ActionMailbox.
+- Yield the same destination from `Mailboxes.receive` so apps can link their
+  business records while retaining gem-managed raw email, metadata and membership
+  persistence. Host exceptions propagate instead of being reported as missing
+  mailbox records; existing no-argument receive blocks continue to work.
+
+- Add a bounded, Rails-independent `Ingress.verify` API for existing ingestion
+  pipelines, with optional ActionMailbox persistence and tenant registry routing.
+- Add opt-in v3 signatures for provider metadata supplied by custom Workers.
+  Metadata is authenticated transport evidence, not proof of sender authenticity.
+  Default Worker forwarding remains v2; upgrade Rails before enabling v3.
+- Verify signatures against exact timestamp header bytes; decimal parsing is
+  used only for freshness. The bundled Worker's timestamp format is unchanged.
+- Add GET-only `cloudflare:email:check_route` diagnostics for exact receiving-domain
+  DNS and Worker routing. Reports uncertainty without changing configuration or
+  claiming live delivery is verified.
+
+- Add an opt-in server-rendered mailbox management engine with host authentication,
+  mailbox/domain scoping and per-action permissions. Manage mailboxes and aliases,
+  suspend/resume, preview plain-text messages and mark read/archive without
+  JavaScript or asset pipeline dependencies. The engine is never mounted by default.
+
+- Fix managed domain and address activation in Rails apps with strict readonly
+  attributes enabled. Normalize immutable identities only when creating records;
+  later lifecycle updates retain the original domain and address.
+
 ## 0.2.0 — 2026-09-11
 
 - Add optional managed mailboxes: domain directory, addresses/aliases, lifecycle,

data/README.md

@@ -2,7 +2,11 @@
 
 Ruby client for [Cloudflare Email Service](https://developers.cloudflare.com/email-service/), with ActionMailer, authenticated ActionMailbox ingress, a forwarding Worker, and optional durable Rails sending and delivery-event tracking.
 
-Version **0.2.0**. Ruby 3.2+, Rails 7.2–8.1; Ruby 4.0 is tested with Rails 8.1. Supported test floors are Rails 7.2.3.2, 8.0.5.1, and 8.1.3.1. Prefer a maintained Ruby/Rails release for new applications. The plain Ruby client uses Ruby's standard libraries plus the Base64 gem. Node is optional: Worker deployment also works through the included Ruby deployer. See [security guidance](SECURITY.md) for deployment responsibilities.
+Version **0.3.0**. Ruby 3.2+, Rails 7.2–8.1; Ruby 4.0 is tested with Rails 8.1. Supported test floors are Rails 7.2.3.2, 8.0.5.1, and 8.1.3.1. Prefer a maintained Ruby/Rails release for new applications. The plain Ruby client uses Ruby's standard libraries plus the Base64 gem. Node is optional: Worker deployment also works through the included Ruby deployer. See [security guidance](SECURITY.md) for deployment responsibilities.
+
+[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cole-robertson/cloudflare-email/tree/main/templates/deploy-to-cloudflare)
+
+Deploy the inbound Worker with guided R2/Queue provisioning and secret setup. [Prepare Rails and connect your email address](templates/deploy-to-cloudflare/README.md).
 
 ## Start here
 
@@ -16,19 +20,25 @@ Version **0.2.0**. Ruby 3.2+, Rails 7.2–8.1; Ruby 4.0 is tested with Rails 8.1
 | [Getting started](docs/getting-started.md) | Install, send your first email, receive replies, and save reliable send operations |
 | [Troubleshooting](docs/troubleshooting.md) | What to check when mail or delivery updates do not arrive |
 | [Managed mailboxes](docs/mailboxes.md) | Create inboxes and aliases, read/archive mail, and send from a mailbox |
+| [Management engine](docs/management-engine.md) | Mount an optional server-rendered mailbox UI using your app's authentication |
+| [Custom ingress](docs/custom-ingress.md) | Reuse authentication, signed metadata, and tenant routing in your existing ingestion pipeline |
+| [Routing diagnostics](docs/routing-diagnostics.md) | Inspect exact-domain DNS and Worker routes without changing infrastructure |
+| [Reusable Worker pipeline](templates/worker/README.md#reuse-the-transport-in-an-existing-worker) | Keep custom backend and archive policies while sharing bounded email forwarding |
+| [Durable inbound delivery](templates/worker/README.md#durable-inbound-delivery) | Store incoming mail in R2 and recover Rails outages with queued retries and scheduled recovery |
+| [Routing delivery confirmation](docs/routing-deliveries.md) | Confirm qualifying normal-address deliveries using authenticated Routing analytics |
 | [SQLite tenant databases](docs/activerecord-tenanted.md) | Give each organization its own SQLite database with `activerecord-tenanted` |
 | [Durable outbox](docs/outbox.md) | Detailed setup, callbacks, retries, and recovery |
 | [Delivery events](docs/delivery-events.md) | Cloudflare Queue setup and recipient status tracking |
-| [Upgrading to 0.2](docs/upgrading-0.2.md) | Changes needed for an existing installation |
+| [Upgrading to 0.3](docs/upgrading-0.3.md) | Changes needed for an existing installation |
 
 The sections below are the configuration and API reference.
 
 ## Install and send from Rails
 
-Add version 0.2 to your Gemfile. Existing 0.1 users should follow the [upgrade guide](docs/upgrading-0.2.md), including the coordinated Rails/Worker update:
+Add version 0.3 to your Gemfile. Existing users should follow the [upgrade guide](docs/upgrading-0.3.md), especially before deploying the durable Worker:
 
 ```ruby
-gem "cloudflare-email", "~> 0.2.0"
+gem "cloudflare-email", "~> 0.3.0"
 ```
 
 ```sh
@@ -209,6 +219,11 @@ Equivalent environment names are `CLOUDFLARE_MANAGEMENT_TOKEN` and `CLOUDFLARE_I
 1. Add the receiving subdomain, for example `in.example.com`, in **Email Routing → apex domain → Settings → Subdomains**. This is a separate onboarding step from sending.
 2. Deploy the environment's Worker and create its route:
 
+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
 RAILS_ENV=production bin/rails cloudflare:email:provision_route ADDRESS=support@in.example.com
@@ -228,18 +243,18 @@ end
 
 `Cloudflare::Email::Envelope.for(inbound_email)` returns a string-keyed `{"from" => "sender@example.com", "to" => "support@example.com"}` hash, or `nil` when the record has no authenticated envelope (for example, another ingress). The metadata is stored on the raw-email blob before routing jobs enqueue. It does not modify the MIME source. Envelope sender information records the SMTP reverse path; it does not authenticate the human sender. An empty `from` is valid for bounces.
 
-Version 0.2 requires the bundled v2 Worker; missing or v1 signatures are rejected. Coordinate Rails and Worker deployment while ingress is paused. The Worker requires ASCII dot-atom addresses, at most 254 bytes with a 64-byte local part. Quoted local parts, address literals, and internationalized addresses are not supported by this envelope format.
+The bundled Worker uses v2 signatures by default; missing or v1 signatures are rejected. The custom-ingress API also supports opt-in v3 signatures carrying authenticated Worker metadata. See [custom ingestion](docs/custom-ingress.md) and upgrade the Rails receiver before enabling v3 in a custom Worker. When upgrading from v1, coordinate Rails and Worker deployment while ingress is paused. Both envelope versions require ASCII dot-atom addresses, at most 254 bytes with a 64-byte local part. Quoted local parts, address literals, and internationalized addresses are not supported by this envelope format.
 
 Successful ingress storage returns HTTP 200; duplicate storage returns 200 too. The timestamp window limits request age, but is not a one-time replay ledger. Version 2 deduplication includes the exact SMTP recipient, so identical MIME delivered to separate To/Cc/Bcc recipients creates separate inbound records while a retry for the same recipient creates none.
 
-The Worker has a 15-second Rails request timeout and rejects redirects. Non-2xx responses, timeouts, and network failures call `message.setReject`. There is no durable buffering of inbound email: an application outage can reject mail. Storage acceptance does not guarantee later mailbox-job success. Monitor Rails jobs and Cloudflare Worker logs.
+The Worker has a 15-second Rails request timeout and rejects redirects. Its default [durable inbound path](templates/worker/README.md#durable-inbound-delivery) saves messages in R2 before acceptance, then retries Rails handoffs through Queues and scheduled recovery. Provision the resources before deploying. `INBOUND_DELIVERY_MODE=direct` selects the single-attempt fallback, which can reject mail during an outage; existing retained mail keeps recovering. Rails storage acceptance does not guarantee later mailbox-job success. Monitor Rails jobs and Cloudflare Worker logs.
 
 ### Local development and deployment
 
-Start Rails, then:
+For a simple development tunnel, use the explicit direct fallback. Start Rails, then:
 
 ```sh
-bin/rails cloudflare:email:deploy_worker
+INBOUND_DELIVERY_MODE=direct bin/rails cloudflare:email:deploy_worker
 bin/rails cloudflare:email:dev
 ```
 
@@ -247,7 +262,7 @@ The dev task requires `cloudflared`, refuses environments other than development
 
 For a custom installer `--worker-dir`, pass `SCRIPT=custom-directory/src/index.js` to the Ruby `deploy_worker` task. The installer prints the corresponding command.
 
-Ruby deployment and Wrangler use matching names: `cloudflare-email-ingress-development`, `-staging`, and `-production`. The optional Wrangler path requires Node 22.12+ (or a supported newer version):
+Ruby deployment and Wrangler use matching names: `cloudflare-email-ingress-development`, `-staging`, and `-production`. Initial durable infrastructure deployment uses Wrangler and requires Node 22.12+ (or a supported newer version):
 
 ```sh
 cd cloudflare-worker
@@ -312,6 +327,8 @@ Cloudflare's current [header documentation](https://developers.cloudflare.com/em
 | `account_id`, `api_token` | Required |
 | `base_url` | `https://api.cloudflare.com/client/v4` |
 | `timeout` | 30 seconds for open/read/write |
+| `total_timeout` | Defaults to `timeout`; bounds one complete HTTP attempt, including headers and streamed body |
+| `max_response_bytes` | 1 MiB for `Client`; 32 MiB for `EventConsumer` queue batches |
 | `retries` | 3 additional attempts |
 | `initial_backoff` | 0.5 seconds, doubling |
 | `max_retry_after` | 60 seconds |
@@ -320,6 +337,14 @@ Cloudflare's current [header documentation](https://developers.cloudflare.com/em
 
 By default, only 429 responses and pre-send connection failures retry. Numeric and HTTP-date `Retry-After` values are honored up to the cap. Read/write timeouts, connection resets, and 5xx responses may occur after acceptance; they raise without automatically resending. Setting `retry_ambiguous: true` restores retries for those failures and can send duplicates.
 
+Responses are streamed with a byte limit, including decompressed content and
+error responses. A total deadline or response-size failure after transmission
+does not prove a send failed: the outbox preserves the ambiguous claim and blocks
+automatic resend. Net::HTTP's implicit retries are disabled. Explicit retries
+and backoff can make a logical call longer than `total_timeout`; queue handlers,
+database transactions and a complete polling run have separate runtime budgets.
+An uncertain queue acknowledgement permits receipt replay, never email resending.
+
 No idempotency key is sent. Reusing Message-ID does not guarantee deduplication or exactly-once delivery. Account for ActiveJob's retry policy too: retrying the whole mailer job can resend even when this client's retries are disabled.
 
 Errors inherit from `Cloudflare::Email::Error`: `ConfigurationError`, `AuthenticationError`, `ValidationError`, `RateLimitError`, `ServerError`, and `NetworkError`. API errors expose `status` and parsed `response`.

data/app/controllers/cloudflare/email/ingress_controller.rb

@@ -1,16 +1,12 @@
-require "cloudflare/email/verification"
+require "cloudflare/email/ingress"
 
 module Cloudflare
   module Email
     # ActionMailbox ingress for Cloudflare Email Worker forwards.
     #
-    # The shipped Worker template signs each forwarded message with HMAC-SHA256
-    # over "v2.{timestamp}.{encoded_envelope}.{raw_body}" and sends:
-    #   X-CF-Email-Timestamp: <unix seconds>
-    #   X-CF-Email-Signature: <hex digest>
-    #   X-CF-Email-Signature-Version: 2
-    #   X-CF-Email-Envelope: <unpadded base64url JSON from/to>
-    # Requests must include the v2 signature and authenticated SMTP envelope.
+    # The default Worker uses v2 authenticated SMTP envelopes; custom Workers
+    # can opt into v3 to authenticate additional provider metadata. Both use
+    # the shared, bounded Ingress verifier before any tenant lookup or storage.
     #
     # Set the shared secret in Rails credentials under cloudflare.ingress_secret
     # (or in the CLOUDFLARE_INGRESS_SECRET env var) and as the Worker secret
@@ -24,45 +20,30 @@ module Cloudflare
           "cloudflare_email.ingress",
           bytes: 0,
         ) do |payload|
-          preflight = Cloudflare::Email::Verification.verify_headers(secret: secret,
-            timestamp: request.headers["X-CF-Email-Timestamp"],
-            signature: request.headers["X-CF-Email-Signature"],
-            version: request.headers["X-CF-Email-Signature-Version"],
-            envelope: request.headers["X-CF-Email-Envelope"])
-          unless preflight == :ok
-            payload[:result] = preflight
-            next head(preflight == :stale ? :request_timeout : :unauthorized)
-          end
-          if request.content_length.to_i > max_email_bytes || raw_body.bytesize > max_email_bytes
-            payload[:result] = :too_large
-            next head(:payload_too_large)
-          end
-          payload[:bytes] = raw_body.bytesize
-          case Cloudflare::Email::Verification.verify(
-                secret:    secret,
-                body:      raw_body,
-                timestamp: request.headers["X-CF-Email-Timestamp"],
-                signature: request.headers["X-CF-Email-Signature"],
-                version: request.headers["X-CF-Email-Signature-Version"],
-                envelope: request.headers["X-CF-Email-Envelope"],
-              )
+          request.body.rewind if request.body.respond_to?(:rewind)
+          result = Cloudflare::Email::Ingress.verify(secret: secret,
+            headers: request.headers, body: request.body,
+            content_length: request.content_length, max_email_bytes: max_email_bytes)
+          payload[:bytes] = result.bytes.to_i
+          payload[:result] = result.status
+          case result.status
           when :stale
-            payload[:result] = :stale
             head :request_timeout
           when :bad_signature
-            payload[:result] = :bad_signature
             head :unauthorized
+          when :too_large
+            head :payload_too_large
           when :ok
             inbound = if defined?(Cloudflare::Email::Mailboxes) && Cloudflare::Email::Mailboxes.enabled?
-              recipient = Cloudflare::Email::Envelope.decode(request.headers["X-CF-Email-Envelope"]).fetch("to")
+              recipient = result.message.envelope.fetch("to")
               begin
-                Cloudflare::Email::Mailboxes.receive(recipient: recipient) { persist_inbound }
+                Cloudflare::Email::Mailboxes.receive(recipient: recipient) { result.message.persist_action_mailbox! }
               rescue Cloudflare::Email::Mailboxes::Unavailable
                 payload[:result] = :unavailable_mailbox
                 next head(:unprocessable_entity)
               end
             else
-              persist_inbound
+              result.message.persist_action_mailbox!
             end
             payload[:result]     = inbound ? :ok : :duplicate
             payload[:message_id] = inbound&.message_id
@@ -73,37 +54,12 @@ module Cloudflare
 
       private
 
-      def persist_inbound
-        envelope = Cloudflare::Email::Envelope.decode(request.headers["X-CF-Email-Envelope"])
-
-        # Commit trusted routing metadata before ActionMailbox's after_create_commit
-        # enqueues routing. Identical MIME for To/Cc/Bcc recipients is independent.
-        checksum = OpenSSL::Digest::SHA256.hexdigest("v2\0#{envelope.fetch('to')}\0".b + raw_body.b)
-        ActionMailbox::InboundEmail.transaction do
-          inbound = ActionMailbox::InboundEmail.create_and_extract_message_id!(raw_body, message_checksum: checksum)
-          if inbound
-            blob = inbound.raw_email.blob
-            blob.update!(metadata: blob.metadata.merge(
-              Cloudflare::Email::Envelope::METADATA_KEY => envelope.merge("version" => 2),
-            ))
-          end
-          inbound
-        end
-      end
-
       # Override ActionMailbox::BaseController's default name inference so
       # `config.action_mailbox.ingress = :cloudflare` gates this controller.
       def ingress_name
         :cloudflare
       end
 
-      def raw_body
-        @raw_body ||= begin
-          request.body.rewind if request.body.respond_to?(:rewind)
-          request.body.read(max_email_bytes + 1).to_s
-        end
-      end
-
       def max_email_bytes
         @max_email_bytes ||= begin
           value = Integer(ENV.fetch("MAX_EMAIL_BYTES", DEFAULT_MAX_EMAIL_BYTES.to_s), 10)

data/app/controllers/cloudflare/email/management/mailboxes_controller.rb

@@ -0,0 +1,173 @@
+module Cloudflare
+  module Email
+    module Management
+      class MailboxesController < ActionController::Base
+        layout "layouts/cloudflare/email/management"
+        protect_from_forgery with: :exception
+        self.forgery_protection_origin_check = true
+        around_action :with_host_context
+        helper_method :allowed?, :host_back_path
+
+        class Denied < StandardError; end
+        class InvalidInput < StandardError; end
+
+        rescue_from Denied do
+          head :forbidden
+        end
+        rescue_from "ActiveRecord::RecordNotFound" do
+          head :not_found
+        end
+        rescue_from InvalidInput, "ActiveRecord::RecordInvalid", Cloudflare::Email::Error do
+          redirect_to(@mailbox ? mailbox_path(@mailbox) : root_path,
+            alert: "The changes could not be saved. Check the address, registered domain and required fields.",
+            status: :see_other)
+        end
+        rescue_from Cloudflare::Email::ConfigurationError do
+          head :service_unavailable
+        end
+
+        def index
+          authorize!(:index)
+          @mailboxes = page(scoped_mailboxes)
+          @domains = permitted_domains if allowed?(:create)
+        end
+
+        def show
+          load_mailbox!(:show)
+          @addresses = @session.addresses(@mailbox.id).order(:id).to_a
+          @domains = allowed?(:add_address, @mailbox) ? permitted_domains : []
+          @messages = allowed?(:show_message, @mailbox) ? page(@session.messages(@mailbox.id)) : []
+        end
+
+        def create
+          authorize!(:create)
+          input = params.require(:mailbox)
+          raise InvalidInput unless input.is_a?(ActionController::Parameters)
+          values = input.permit(:name, :address)
+          name = values[:name].to_s.strip
+          raise InvalidInput unless (1..255).cover?(name.length)
+          address = permitted_address!(values[:address])
+          Mailboxes::Mailbox.transaction do
+            @mailbox = @adapter.create_mailbox(@session, name: name, address: address)
+            # A hook cannot turn an arbitrary return value into a readable mailbox.
+            @mailbox = scoped_mailboxes.find(@mailbox.id)
+          end
+          redirect_to mailbox_path(@mailbox), notice: "Mailbox created. Review address setup below.", status: :see_other
+        end
+
+        def add_address
+          load_mailbox!(:add_address)
+          @adapter.add_address(@session, @mailbox, address: permitted_address!(params[:address]))
+          redirect_to mailbox_path(@mailbox), notice: "Address added. Review its setup status.", status: :see_other
+        end
+
+        def suspend
+          load_mailbox!(:suspend)
+          @session.suspend(@mailbox.id)
+          redirect_to mailbox_path(@mailbox), notice: "Mailbox suspended. Messages are retained.", status: :see_other
+        end
+
+        def resume
+          load_mailbox!(:resume)
+          @session.resume(@mailbox.id)
+          redirect_to mailbox_path(@mailbox), notice: "Mailbox resumed. Pending addresses still need setup.", status: :see_other
+        end
+
+        def message
+          load_mailbox!(:show_message)
+          @entry = @session.messages(@mailbox.id).find(params[:message_id])
+          raw = @session.inbound_email(@mailbox.id, @entry.id).mail
+          @subject = raw.subject.to_s
+          @from = Array(raw.from).join(", ")
+          part = raw.text_part || (raw.mime_type == "text/plain" ? raw : nil)
+          @body = part ? part.decoded.to_s.encode("UTF-8", invalid: :replace, undef: :replace).first(100_000) :
+            "This message has no plain-text body. HTML rendering is disabled in this management interface."
+          @attachments = raw.attachments.map { |attachment| attachment.filename.to_s }
+          render :message
+        end
+
+        def mark_read
+          load_mailbox!(:mark_read)
+          @session.mark_read(@mailbox.id, params[:message_id], read: boolean_param(:read))
+          redirect_to mailbox_path(@mailbox), status: :see_other
+        end
+
+        def archive
+          load_mailbox!(:archive)
+          @session.archive(@mailbox.id, params[:message_id], archived: boolean_param(:archived))
+          redirect_to mailbox_path(@mailbox), status: :see_other
+        end
+
+        private
+
+        def with_host_context
+          response.headers["Cache-Control"] = "no-store"
+          response.headers["Referrer-Policy"] = "same-origin"
+          response.headers["X-Content-Type-Options"] = "nosniff"
+          response.headers["Content-Security-Policy"] = "default-src 'none'; style-src 'self'; img-src 'none'; form-action 'self'; frame-ancestors 'none'; base-uri 'none'"
+          factory = Management.configuration.adapter
+          unless factory.respond_to?(:call) && defined?(Mailboxes) && Mailboxes.enabled?
+            return head :service_unavailable
+          end
+          @adapter = factory.call(self)
+          authenticated = @adapter.authenticate!
+          return if performed?
+          return head :unauthorized unless authenticated == true
+          Mailboxes.for_tenant(@adapter.tenant_key) do |session|
+            @session = session
+            yield
+          end
+        end
+
+        def allowed?(action, mailbox = nil)
+          @adapter.allowed?(action, mailbox) == true
+        end
+
+        def authorize!(action, mailbox = nil)
+          raise Denied unless allowed?(action, mailbox)
+        end
+
+        def scoped_mailboxes
+          # Always retain the gem's tenant condition even if a host scope omits it.
+          @session.mailboxes.where(id: @adapter.mailboxes(@session).reselect(:id))
+        end
+
+        def load_mailbox!(action)
+          @mailbox = scoped_mailboxes.find(params[:id])
+          authorize!(action, @mailbox)
+        end
+
+        def permitted_domains
+          granted = Array(@adapter.domains(@session)).map(&:to_s)
+          Mailboxes::ReceivingDomain.active.where(tenant_key: @session.tenant_key, domain: granted).order(:domain).pluck(:domain)
+        end
+
+        def permitted_address!(value)
+          address = Mailboxes.canonical_address(value)
+          raise InvalidInput unless permitted_domains.include?(address.split("@", 2).last)
+          address
+        end
+
+        def page(relation)
+          cursor = params[:after].to_s
+          raise InvalidInput unless cursor.empty? || cursor.match?(/\A[0-9]{1,18}\z/)
+          rows = relation.where("id > ?", cursor.to_i).order(:id).limit(51).to_a
+          @next_cursor = rows.length > 50 ? rows[49].id : nil
+          rows.first(50)
+        end
+
+        def boolean_param(key)
+          value = params[key]
+          raise InvalidInput unless %w[true false].include?(value)
+          value == "true"
+        end
+
+        def host_back_path
+          callback = Management.configuration.back_path
+          value = callback.call(self) if callback.respond_to?(:call)
+          value if value.is_a?(String) && value.start_with?("/") && !value.start_with?("//") && !value.match?(/[\\\r\n]/)
+        end
+      end
+    end
+  end
+end

data/app/controllers/cloudflare/email/management/styles_controller.rb

@@ -0,0 +1,13 @@
+module Cloudflare
+  module Email
+    module Management
+      class StylesController < ActionController::Base
+        def show
+          response.headers["X-Content-Type-Options"] = "nosniff"
+          send_data File.binread(File.expand_path("../../../../../lib/cloudflare/email/management/management.css", __dir__)),
+            type: "text/css; charset=utf-8", disposition: "inline"
+        end
+      end
+    end
+  end
+end

data/app/views/cloudflare/email/management/mailboxes/index.html.erb

@@ -0,0 +1,65 @@
+<div class="page-heading">
+  <div>
+    <p class="eyebrow">Email workspace</p>
+    <h1>Mailboxes</h1>
+    <p class="muted">Manage accepted addresses and the messages delivered to them.</p>
+  </div>
+</div>
+
+<div class="workspace-grid">
+  <section class="panel" aria-labelledby="mailboxes-heading">
+    <div class="panel-heading"><h2 id="mailboxes-heading">Your mailboxes</h2></div>
+    <% if @mailboxes.empty? %>
+      <div class="empty-state">
+        <h3>No mailboxes to show</h3>
+        <p>Create a mailbox to give incoming email a home.</p>
+      </div>
+    <% else %>
+      <ul class="record-list">
+        <% @mailboxes.each do |mailbox| %>
+          <li class="record-row">
+            <div class="record-content">
+              <% if allowed?(:show, mailbox) %>
+                <%= link_to mailbox.name, mailbox_path(mailbox.id), class: "record-title" %>
+              <% else %>
+                <span class="record-title"><%= mailbox.name %></span>
+              <% end %>
+              <p class="muted small">Mailbox #<%= mailbox.id %></p>
+            </div>
+            <span class="badge"><%= mailbox.state.capitalize %></span>
+          </li>
+        <% end %>
+      </ul>
+    <% end %>
+    <% if @next_cursor.present? %>
+      <nav class="pagination" aria-label="Mailbox pages">
+        <%= link_to "Next mailboxes →", root_path(after: @next_cursor), class: "button button-secondary" %>
+      </nav>
+    <% end %>
+  </section>
+
+  <% if allowed?(:create) %>
+    <section class="panel" aria-labelledby="create-heading">
+      <div class="panel-heading"><h2 id="create-heading">Create a mailbox</h2></div>
+      <div class="panel-body">
+        <% if @domains.empty? %>
+          <p class="muted">An administrator needs to register an active receiving domain before you can create a mailbox.</p>
+        <% else %>
+          <%= form_with url: mailboxes_path, scope: :mailbox, local: true, class: "stack" do |form| %>
+            <div class="field">
+              <%= form.label :name, "Mailbox name" %>
+              <%= form.text_field :name, required: true, maxlength: 255, placeholder: "Customer support" %>
+            </div>
+            <div class="field">
+              <%= form.label :address, "Email address" %>
+              <%= form.email_field :address, required: true, maxlength: 254, placeholder: "support@#{@domains.first}", aria: { describedby: "create-domains" } %>
+              <p id="create-domains" class="field-help">Available domains: <%= @domains.join(", ") %></p>
+            </div>
+            <p class="field-help">New addresses start pending. Your administrator must confirm their routing before they can receive mail.</p>
+            <%= form.submit "Create mailbox", class: "button" %>
+          <% end %>
+        <% end %>
+      </div>
+    </section>
+  <% end %>
+</div>

data/app/views/cloudflare/email/management/mailboxes/message.html.erb

@@ -0,0 +1,34 @@
+<nav class="breadcrumbs" aria-label="Breadcrumb">
+  <%= link_to "Mailboxes", root_path %> <span aria-hidden="true">/</span>
+  <%= link_to @mailbox.name, mailbox_path(@mailbox.id) %> <span aria-hidden="true">/</span>
+  <span>Message</span>
+</nav>
+<div class="page-heading">
+  <div><p class="eyebrow">Received message</p><h1><%= @subject.presence || "(No subject)" %></h1></div>
+  <div class="actions">
+    <% if allowed?(:mark_read, @mailbox) %>
+      <%= button_to(@entry.read_at ? "Mark unread" : "Mark read", mark_read_mailbox_path(@mailbox.id), method: :post, params: { message_id: @entry.id, read: @entry.read_at ? "false" : "true" }, class: "button button-secondary") %>
+    <% end %>
+    <% if allowed?(:archive, @mailbox) %>
+      <%= button_to(@entry.archived_at ? "Unarchive" : "Archive", archive_mailbox_path(@mailbox.id), method: :post, params: { message_id: @entry.id, archived: @entry.archived_at ? "false" : "true" }, class: "button button-secondary") %>
+    <% end %>
+  </div>
+</div>
+<article class="panel" aria-label="Email message">
+  <div class="panel-body">
+    <dl class="message-metadata">
+      <dt>From</dt><dd><%= @from.presence || "(Unknown sender)" %></dd>
+      <dt>To</dt><dd><%= @entry.recipient %></dd>
+      <dt>Received</dt><dd><time datetime="<%= @entry.created_at.iso8601 %>"><%= @entry.created_at.utc.strftime("%b %-d, %Y · %H:%M UTC") %></time></dd>
+      <dt>Status</dt><dd><%= @entry.read_at ? "Read" : "Unread" %><%= " · Archived" if @entry.archived_at %></dd>
+    </dl>
+  </div>
+  <div class="message-body"><pre><%= @body.presence || "No text content is available for this message." %></pre></div>
+  <% if @attachments.any? %>
+    <section class="panel-body attachments" aria-labelledby="attachments-heading">
+      <h2 id="attachments-heading">Attachments</h2>
+      <p class="field-help">File names are shown for reference. Downloads are not available in this dashboard.</p>
+      <ul><% @attachments.each do |filename| %><li><%= filename.presence || "Unnamed attachment" %></li><% end %></ul>
+    </section>
+  <% end %>
+</article>