cloudflare-email 0.1.0 → 0.2.0

data/SECURITY.md

@@ -0,0 +1,51 @@
+# Security
+
+The hardening described here is included in 0.2.0. Version 0.1.0 does not include
+these fixes. Upgrade Rails and the bundled Worker together using the
+[upgrade guide](docs/upgrading-0.2.md).
+
+Rails integration is tested on patched Rails 7.2, 8.0, and 8.1; application
+owners must update their own Rails, database adapter, and other dependencies.
+The gem does not add Rails or SQLite as runtime dependencies.
+
+Report sensitive findings privately to the maintainer at cole@dscribeai.com.
+Include affected versions and impact; omit real credentials and private mail.
+Do not place secrets or private message data in public issues.
+
+## Deployment responsibilities
+
+- Keep API and management tokens least-privileged and separate. Store tokens and
+  a strong ingress secret in a secret manager or Rails encrypted credentials.
+  Rotate compromised secrets on Rails and the Worker together. HTTPS endpoint
+  overrides are trusted operator configuration; never derive them from mail.
+- Set request-size limits, timeouts and rate limits at the proxy/server. Rails
+  and the Worker bound MIME reads to 25 MiB by default (`MAX_EMAIL_BYTES`), but
+  cannot prevent upstream buffering or slow clients. Limits apply to raw MIME,
+  not just decoded attachments.
+- Treat mail and attachments as untrusted content. The gem authenticates Worker
+  transport and SMTP envelope metadata, not a human sender's identity. Rendering,
+  sanitization, malware scanning and application authorization belong to the app.
+- Protect raw MIME, attachments, outbox snapshots and event receipts with access
+  control, storage encryption, backups and retention policies. Avoid logging raw
+  responses/errors: provider details and application logs can contain private mail.
+- Restrict queue producers and consumers. Event account/domain checks are
+  validation, not cryptographic signatures. Monitor unacknowledged malformed
+  messages, processing failures and unmatched receipts.
+- Database administrators and direct SQL writes are trusted. ActiveRecord
+  read-only evidence fields do not provide tamper-proof storage. Keep tenant
+  authorization around outbox operations and receipt access in the application.
+- The optional mailbox session scopes tenant and mailbox access, but does not
+  authenticate users. Keep domain registration/activation administrative, verify
+  ownership externally, and use your access resolver to choose tenant keys.
+  Ingress selects a registered tenant only after full signature verification.
+  Raw ActiveRecord access remains privileged, especially in shared-database mode.
+  Private tenant storage, consistent migrations and trusted job payloads are
+  required. Drain old framework jobs before enabling database tenancy; jobs
+  without the new tenant metadata are rejected rather than guessing a tenant.
+- Development tunnels expose the ingress to the internet. Use the bundled task,
+  dedicated development mail routes and test data; stop tunnels when finished.
+  The Host guard restricts routing but is not a sandbox for the development app
+  or a replacement for safe error pages and request logging.
+
+See [the September 11 security review](docs/verification/2026-09-11-security.md)
+for findings, verification, and remaining limits.

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

@@ -5,26 +5,46 @@ module Cloudflare
     # ActionMailbox ingress for Cloudflare Email Worker forwards.
     #
     # The shipped Worker template signs each forwarded message with HMAC-SHA256
-    # over "{timestamp}.{raw_body}" and sends:
+    # 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.
     #
     # Set the shared secret in Rails credentials under cloudflare.ingress_secret
     # (or in the CLOUDFLARE_INGRESS_SECRET env var) and as the Worker secret
     # INGRESS_SECRET via `wrangler secret put INGRESS_SECRET`.
     class IngressController < ActionMailbox::BaseController
+      DEFAULT_MAX_EMAIL_BYTES = 25 * 1024 * 1024
       param_encoding :create, "raw_email", Encoding::ASCII_8BIT
 
       def create
         ActiveSupport::Notifications.instrument(
           "cloudflare_email.ingress",
-          bytes: raw_body.bytesize,
+          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"],
               )
           when :stale
             payload[:result] = :stale
@@ -33,9 +53,19 @@ module Cloudflare
             payload[:result] = :bad_signature
             head :unauthorized
           when :ok
-            inbound = ActionMailbox::InboundEmail.create_and_extract_message_id!(raw_body)
-            payload[:result]     = :ok
-            payload[:message_id] = inbound.message_id
+            inbound = if defined?(Cloudflare::Email::Mailboxes) && Cloudflare::Email::Mailboxes.enabled?
+              recipient = Cloudflare::Email::Envelope.decode(request.headers["X-CF-Email-Envelope"]).fetch("to")
+              begin
+                Cloudflare::Email::Mailboxes.receive(recipient: recipient) { persist_inbound }
+              rescue Cloudflare::Email::Mailboxes::Unavailable
+                payload[:result] = :unavailable_mailbox
+                next head(:unprocessable_entity)
+              end
+            else
+              persist_inbound
+            end
+            payload[:result]     = inbound ? :ok : :duplicate
+            payload[:message_id] = inbound&.message_id
             head :ok
           end
         end
@@ -43,6 +73,24 @@ 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
@@ -52,7 +100,15 @@ module Cloudflare
       def raw_body
         @raw_body ||= begin
           request.body.rewind if request.body.respond_to?(:rewind)
-          request.body.read
+          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)
+          raise ArgumentError, "MAX_EMAIL_BYTES must be positive" unless value.positive?
+          value
         end
       end
 

data/docs/activerecord-tenanted.md

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

data/docs/architecture.md

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

data/docs/delivery-events.md

@@ -0,0 +1,177 @@
+# Delivery events
+
+Cloudflare Email Sending can publish outbound lifecycle events to Queues. This is separate from inbound Email Routing and the ActionMailbox ingress.
+
+## Provision once
+
+1. Create a dedicated Cloudflare Queue for your application's sending events.
+2. In that queue's **Subscriptions** tab, subscribe to Email Sending events for your verified sending domain. Subscriptions are domain-specific; add another for each sending domain you need.
+3. Select delivered, deferred, bounced, failed, rejected, and complained events.
+4. Enable **HTTP pull** as the queue consumer. Do not also attach a Worker push consumer.
+5. Configure queue retries and a dead-letter queue so failed or unsupported events can be investigated instead of disappearing after retry exhaustion.
+6. Create an account-scoped **Queues Read + Write** token (dashboard Queues Edit). Writing is necessary to acknowledge messages.
+
+These are explicit Cloudflare setup steps, not actions performed by installing this gem. See [subscription management](https://developers.cloudflare.com/queues/event-subscriptions/manage-event-subscriptions/) and [HTTP pull consumers](https://developers.cloudflare.com/queues/configuration/pull-consumers/).
+
+## Rails setup
+
+Add credentials:
+
+```yaml
+cloudflare:
+  account_id: your-account-id
+  queues_token: your-queues-read-write-token
+  event_queue_id: your-queue-id
+```
+
+Environment alternatives are `CLOUDFLARE_ACCOUNT_ID`, `CLOUDFLARE_QUEUES_TOKEN`, and `CLOUDFLARE_EVENT_QUEUE_ID`. Queue consumption uses its own token; it does not use the management-token fallback.
+
+Configure a callable application handler:
+
+```ruby
+# config/initializers/cloudflare_delivery_events.rb
+Rails.application.configure do
+  config.x.cloudflare_email.event_domains = ["mail.example.com"]
+  config.x.cloudflare_email.event_handler = ->(event) {
+    DeliveryEventProcessor.call(event)
+  }
+end
+```
+
+`DeliveryEventProcessor` supplies application correlation and policy. For Rails,
+use the optional durable receipt adapter below to avoid implementing receipt
+storage, deduplication and replay yourself. Custom handlers must persist durably
+before returning; do not merely enqueue a non-durable job.
+
+### Durable Rails receipts
+
+If you also use the [durable outbox](outbox.md), prefer `DeliveryEvents.record`
+and `DeliveryEvents.replay`: they provide account/message/recipient correlation
+and state ordering automatically. The lower-level example below supports an
+application's own delivery schema.
+
+```sh
+bin/rails generate cloudflare:email:tracking
+bin/rails db:migrate
+```
+
+The generator installs a receipt table and an initializer that explicitly loads
+`cloudflare/email/active_record/event_inbox`. ActiveRecord is not loaded by the
+plain Ruby client. Configure the queue handler to commit receipts:
+
+```ruby
+Rails.application.config.x.cloudflare_email.event_handler = ->(event) {
+  Cloudflare::Email::ActiveRecord::EventInbox.record(event)
+}
+```
+
+Run replay from your recurring job and after saving a send's provider ID:
+
+```ruby
+Cloudflare::Email::ActiveRecord::EventInbox.replay(account_id: account_id) do |event|
+  # Your own model; always scope by account, message AND recipient.
+  delivery = RecipientDelivery.find_by(
+    account_id: event.account_id,
+    provider_message_id: Cloudflare::Email::MessageId.normalize(event.message_id),
+    recipient: event.recipient,
+  )
+  next :unmatched unless delivery
+
+  delivery.with_lock do
+    if event.supersedes?(occurred_at: delivery.occurred_at, terminal: delivery.terminal?)
+      delivery.update!(status: event.status, occurred_at: event.occurred_at,
+                       terminal: event.terminal?)
+    end
+  end
+  :applied
+end
+```
+
+`record` stores the raw event and enforces uniqueness by account/event ID. An ID
+repeated with different content raises. Recording inside an existing database
+transaction raises, because returning before that transaction commits would allow
+premature acknowledgment. An acknowledged receipt can still be pending or unmatched;
+monitor and schedule replay separately from queue polling.
+
+`apply(receipt) { |event| ... }` and `replay` lock each receipt and skip applied
+records. Handlers must return `:applied` or `:unmatched`; exceptions and other return
+values roll back the receipt transition and writes on the same database connection.
+`:unmatched` is a successful transaction outcome, so avoid business writes before
+returning it. External effects and writes to other databases cannot be rolled back.
+Concurrent database conflicts raise; retry the job. Do not send email inside this
+handler; use durable outbound orchestration.
+
+Replay accepts optional `account_id:`, normalized provider `message_id:`, and
+`batch_size:` filters. The batch size controls database fetch size, not the total
+number processed. `DeliveryEvent#supersedes?` accepts a Time or ISO8601 previous
+timestamp: only a newer known status replaces current state, equal timestamps keep
+existing state, and a nonterminal event cannot replace terminal state. A later
+terminal complaint can replace delivery. Invalid timestamps raise. Match records
+and lock recipient state before using this ordering helper.
+
+Receipt retention, recurring jobs, and monitoring are application decisions. See
+the [gem/inbox boundary](architecture.md) for outbound-ledger scope. Existing
+receipt tables from the earlier preproduction adapter must normalize stored
+`message_id` values with `MessageId.normalize` before using filtered replay;
+raw payloads remain unchanged. The reference inbox's outbox migration does this.
+
+Poll a single batch:
+
+```sh
+bin/rails cloudflare:email:consume_events
+BATCH_SIZE=20 bin/rails cloudflare:email:consume_events
+```
+
+Run the task from your existing scheduler, or invoke `EventConsumer#poll` from a recurring job. It short-polls once and exits; an empty queue is a successful result. No handler means an error before any queue request, not automatic discard.
+
+For more control, use the API directly:
+
+```ruby
+consumer = Cloudflare::Email::EventConsumer.new(
+  account_id: Cloudflare::Email::Credentials.account_id,
+  api_token: Cloudflare::Email::Credentials.fetch(:queues_token),
+  queue_id: Cloudflare::Email::Credentials.fetch(:event_queue_id),
+  domains: ["mail.example.com"],
+)
+
+count = consumer.poll(batch_size: 5, visibility_timeout_ms: 300_000) do |event|
+  DeliveryEventProcessor.call(event)
+end
+```
+
+The same API works in plain Ruby with explicit credentials.
+
+## Event data
+
+| Method | Meaning |
+|---|---|
+| `event_id` | Durable application deduplication key |
+| `message_id` | Cloudflare message ID for correlation with the send response |
+| `status` | delivered, deferred, bounced, failed, rejected, complained |
+| `known?` | Whether status is one of those six current types |
+| `terminal?` | Cloudflare's terminal flag; not a guarantee no later complaint arrives |
+| `sender`, `recipient` | Addresses from the event |
+| `account_id`, `domain` | Event source, checked against consumer configuration |
+| `occurred_at` | Original event timestamp string |
+| `delivery`, `bounce`, `rejection`, `failure`, `complaint` | Detail hashes |
+| `raw`, `payload`, `type` | Original provider data |
+
+Record outcomes per message **and recipient**. A delivery event means the recipient's server accepted the message, not that the person read it. Use bounce/complaint events to maintain your application's recipient eligibility and unsubscribe state. Cloudflare's own suppression behavior remains controlled by Cloudflare; the consumer does not automatically edit provider suppression lists or your database.
+
+Events can be duplicated or arrive out of order. Do not blindly overwrite a newer terminal state with an older deferred event. Decide how your application handles a complaint after delivery. Provider IDs may be absent from older send responses; retain event data even when an application record cannot yet be found.
+
+## Processing guarantees
+
+For each message, the consumer decodes the body, validates the event, invokes your handler, and then acknowledges its lease. Email Sending subscriptions can return plain JSON strings with `CF-Content-Type: json`; the consumer also accepts base64-encoded JSON for that content type. `bytes` bodies contain base64-encoded JSON, while `text` bodies contain JSON directly. Invalid bodies and events remain unacknowledged.
+
+- A handler that returns normally counts as successful, even if its return value is `false` or `nil`. **Raise** to prevent acknowledgement.
+- A parse error, mismatched account/domain, handler exception, or acknowledgement failure stops the batch. Previously acknowledged messages remain acknowledged; the current and remaining leases become available after the visibility timeout.
+- If the handler commits and acknowledgement fails, the event can be processed again. This is why the handler needs durable idempotency.
+- Automatic HTTP retries are disabled for queue calls. Your scheduler can retry the next poll.
+- The default batch size is 5 (max 100); the default visibility window is five minutes. Choose a window longer than the **whole batch's** worst-case processing time, up to Cloudflare's 12-hour maximum.
+- Unknown future status names in schema version 1 are passed through with `known? == false`. Decide whether to store or raise. Unsupported schema versions are rejected and left unacknowledged.
+- Configure dead-letter retention/alerts. Repeated failure eventually exhausts the queue's retry policy.
+
+The `cloudflare_email.delivery_event` notification wraps handler execution with event ID, message ID, and status. It does not mean acknowledgement succeeded. Monitor task/job failures as well.
+
+Source schemas: [Email Sending event subscriptions](https://developers.cloudflare.com/email-service/platform/event-subscriptions/), [pull API](https://developers.cloudflare.com/api/resources/queues/subresources/messages/methods/pull/), [ack API](https://developers.cloudflare.com/api/resources/queues/subresources/messages/methods/ack/).