cloudflare-email 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c65b29d22af39c25cb2affb776984bc9a9086bcad75c7388c2017692f61eb9ef
-  data.tar.gz: 2c0d1f15f4159e780257260af62cca8d414c7cc00d7c1c8b2677ac243cf81b04
+  metadata.gz: b53307e62ade70f522e0fcb5705e11552e9718914d02bea8754a11653b15349a
+  data.tar.gz: 692c09a19fcb4ccd9295ccb692a19bf02aba3176b107c8500e5450b100ce1df3
 SHA512:
-  metadata.gz: 4b76b7c08c99da504f7c90bbfb79f6f3130345e128c0fad9988a1449270d79019ffa5af8fb62a0759ad881c56019ffe6d9f6b967d13136e988b9e98ef6d7043e
-  data.tar.gz: d3f2d2573c6d41140ceff2395c4aa84194eb10ad2c56379df133f1fa1687424b009513800e4c67d1077584750146c2f5b9e0dfedfb53d2b9a351c5f207f80636
+  metadata.gz: 43da0e85cde52970e696d5a2dfd74f03c0f39f5ea7d66e33cd28ec2bb58e5872c57db7f5dbc010ab85ad43312de9c9abcf2eed31a65e01f78fed8b6de164483b
+  data.tar.gz: a38902643ce082d656a01b7d91a34e70f95f15d66de6fd06e1fe7502461ae6d155a64edcea780155dd9b00b055635a3b10d5a0e9d8cbf2d077e1a7782742b193

data/CHANGELOG.md

@@ -1,9 +1,38 @@
 # Changelog
 
+## 0.4.1 — 2026-10-06
+
+- Report the provider's own reason when a refused request returns a body that
+  is not a Cloudflare JSON object. Cloudflare Queues throttles a pull with
+  `429` and the bare text `Queue is overloaded. Please back off.`; that raised
+  `RateLimitError: invalid JSON API response; request outcome is unknown`, which
+  dropped the reason and called a known refusal unknown. It now raises
+  `RateLimitError: HTTP 429: Queue is overloaded. Please back off.` The text is
+  collapsed to one line and capped at 200 characters; an HTML error page is
+  still never echoed. A `5xx` keeps "request outcome is unknown" because it may
+  have failed after taking effect, and an unreadable `2xx` still fails closed.
+  Error classes and retry behaviour are unchanged.
+- Honour `Retry-After` on a `429` whose body is a bare JSON string. The parsed
+  string was not a Hash, so the header was never stashed and the retry slept
+  the default backoff instead.
+- Describe an unreadable provider response as an unknown *request* outcome rather
+  than an unknown *delivery* outcome. `Client#request` serves every caller, so a
+  queue pull that timed out reported that a delivery outcome was unknown when no
+  message was in flight — sending operators to look for an email that never
+  existed.
+
+  This message reaches **every** caller of `Client#request`, sending included:
+  nothing wraps or rescues it in `DeliveryMethod` or `Outbox.deliver`, and
+  `SendJob`'s "delivery outcome is unknown; reconcile before retrying" is a
+  separate condition (retrying a delivery already in the `unknown` state), not a
+  wrapper around this error. A send caller now reads "request outcome is unknown",
+  which remains accurate for a send — the request *is* the send — and stops the
+  same string from asserting a delivery on the paths that never had one.
+
 ## 0.4.0 — 2026-09-14
 
 Released alongside Mailbox Kit 0.1.0. Cloudflare installs the core automatically.
-Existing installations should follow the [core upgrade guide](mailbox-kit/docs/upgrading.md).
+Existing installations should follow the [core upgrade guide](maintainer/upgrading-mailbox-kit.md).
 
 - Allow receiving domains without a sending account. The upgrade generator
   preserves existing directory records while making account ownership optional.
@@ -35,7 +64,7 @@ Existing installations should follow the [core upgrade guide](mailbox-kit/docs/u
 
 ## 0.3.0 — 2026-09-13
 
-See [upgrading from 0.2](docs/upgrading-0.3.md) before deploying the updated Worker.
+See [upgrading from 0.2](maintainer/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

data/README.md

@@ -1,177 +1,78 @@
-# cloudflare-email
+# Cloudflare Email
 
-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.
+Send and receive email in Ruby and Rails through [Cloudflare Email Service](https://developers.cloudflare.com/email-service/).
 
-Version **0.4.0**, with **Mailbox Kit 0.1.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. Rails and database dependencies remain optional for the plain Ruby client. Node is optional: Worker deployment also works through the included Ruby deployer. See [security guidance](SECURITY.md) for deployment responsibilities.
+Use your existing Rails mailers, receive messages through Action Mailbox, and add
+persistent inboxes with [Mailbox Kit](mailbox-kit/README.md). SQLite is supported.
+Database tenancy and the management UI are optional.
 
-[![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
-
-**Starting in 0.4.0:** provider-neutral mailbox functionality lives in
-the sibling [Mailbox Kit](mailbox-kit/README.md) gem. Existing Cloudflare setup
-continues to work; the core requires no Cloudflare account. Installing
-`cloudflare-email` also installs `mailbox-kit` 0.1.x.
-Existing mailbox installations should use the [core upgrade guide](mailbox-kit/docs/upgrading.md)
-to add the inbound lookup index without recreating their tables.
-
-**Sending email?** Start with the [step-by-step Rails guide](docs/getting-started.md).
-**Building a mailbox?** Follow the same guide through receiving, the SQLite-compatible outbox, and delivery tracking.
-**Using plain Ruby?** Jump to [Plain Ruby](#plain-ruby); Rails and a database are optional.
-
-| Guide | What you will learn |
-| --- | --- |
-| [Features at a glance](docs/features.md) | Everything the gem handles, and what your app supplies |
-| [Getting started](docs/getting-started.md) | Install, send your first email, receive replies, and save reliable send operations |
-| [Cloudflare domain setup](templates/worker/docs/domain-setup.md) | Configure once for many mailboxes or dynamic organization subdomains, with a Rebulk example and DNS checks |
-| [Hello-world Rails template](https://github.com/cole-robertson/cloudflare-email-rails-starter) | Clone a minimal SQLite mailbox app using the published gem and its management UI |
-| [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.4](mailbox-kit/docs/upgrading.md) | Core extraction and data-preserving migrations for existing mailboxes |
-| [Upgrading from 0.2](docs/upgrading-0.3.md) | Additional changes before deploying the durable Worker |
-
-The sections below are the configuration and API reference.
-
-## Install and send from Rails
-
-Add version 0.4 to your Gemfile. Existing mailbox users should follow the [core upgrade guide](mailbox-kit/docs/upgrading.md). When upgrading from 0.2, also follow the [durable Worker upgrade guide](docs/upgrading-0.3.md):
+## Install
 
 ```ruby
 gem "cloudflare-email", "~> 0.4.0"
 ```
 
+Mailbox Kit installs automatically. If you use another email provider, you can
+[use Mailbox Kit on its own](mailbox-kit/README.md).
+
+Requires Ruby 3.2+; Rails integrations support Rails 7.2–8.1.
+Use a current patch release. Plain Ruby sending does not require Rails or a database.
+
+## Send from Rails
+
 ```sh
 bundle install
 bin/rails generate cloudflare:email:install --no-inbound
 ```
 
-Add Rails credentials (encrypted, per environment) or environment variables:
-
-```yaml
-cloudflare:
-  account_id: your-account-id
-  api_token: your-email-sending-token
-```
+[Verify a sending domain in Cloudflare](https://developers.cloudflare.com/email-service/configuration/domains/)
+and add your account ID and sending token:
 
 ```sh
 export CLOUDFLARE_ACCOUNT_ID=your-account-id
 export CLOUDFLARE_API_TOKEN=your-email-sending-token
 ```
 
-The generated initializer uses `Cloudflare::Email::Credentials`: nonempty Rails credentials take precedence, then `CLOUDFLARE_*` environment variables. For an existing 0.1.0 installation, update the initializer manually; see [upgrading](docs/upgrading-0.2.md).
-
-Onboard a sending domain under **Compute → Email Service → Email Sending**. Use a dedicated sending subdomain if the apex already uses another mail provider. Cloudflare's onboarding adds the required bounce MX, SPF, DKIM, and DMARC records for that sending domain. Follow the current [domain configuration](https://developers.cloudflare.com/email-service/configuration/domains/) instructions; do not replace an existing apex SPF record or publish a second one.
-
-Create a token with permission to send for your account, and verify the domain in the dashboard before testing:
-
-```sh
-bin/rails cloudflare:email:doctor
-FROM=hello@mail.example.com TO=you@example.net bin/rails cloudflare:email:send_test
-```
-
-`doctor` checks configuration and available read access. It does not send mail or prove deliverability. `send_test` requires both `FROM` and `TO`.
-
-Standard ActionMailer works:
+Your regular mailers can now send through Cloudflare:
 
 ```ruby
-class WelcomeMailer < ApplicationMailer
-  def welcome(user)
-    mail(from: "hello@mail.example.com", to: user.email, subject: "Welcome") do |format|
-      format.text { render plain: "Hello!" }
+class HelloMailer < ApplicationMailer
+  def hello(address)
+    mail(from: "hello@mail.example.com", to: address, subject: "Hello") do |format|
+      format.text { render plain: "Hello from Rails!" }
     end
   end
 end
 
-WelcomeMailer.welcome(user).deliver_later
-```
-
-Multipart, attachments, cc/bcc, and threading headers are serialized through `send_raw`. Cloudflare still controls final delivery and header acceptance.
-
-## Managed mailboxes and optional tenancy
-
-**Multi-tenancy is off by default.** Installing the gem does not create tenant
-databases, install a tenancy library, or change your application's database routing.
-
-| Setup | What you explicitly enable |
-| --- | --- |
-| Plain Ruby sending | Nothing extra; no Rails/database required |
-| Managed mailboxes in one database | Run the mailbox generator and load the optional module |
-| Separate tenant databases | Configure `Tenancy.configure(...)` with your application's base class and switching adapter before loading models |
-
-The mailbox API uses a tenant key to group and scope records even in one database.
-That key alone does not enable database switching. `activerecord-tenanted` is an
-optional application dependency, not a runtime dependency of this gem.
-
-Create mailboxes in code with the optional mailbox module. It includes named
-mailboxes, aliases, ownership references, read/archive state, retained raw mail,
-mailbox-authorized sends, and tenant-aware delivery-event recovery:
-
-```sh
-bin/rails generate cloudflare:email:mailboxes
-bin/rails db:migrate
+HelloMailer.hello("you@example.net").deliver_now
 ```
 
-After registering and verifying a receiving domain:
+HTML templates, attachments, multipart messages, cc/bcc, and reply headers work
+through Action Mailer. Follow the [Rails setup guide](docs/getting-started.md)
+for receiving and delivery tracking.
 
-```ruby
-Cloudflare::Email::Mailboxes.for_tenant("organization-123") do |inboxes|
-  mailbox = inboxes.create(name: "Support", address: "support@acme.example.com",
-    owner_ref: "team:42")
-  # Provision and activate its address route before receiving or sending mail.
-end
-```
+## Receive email
 
-Use one database or an application-provided tenant base class. The optional
-`activerecord-tenanted` integration is tested with separate SQLite databases,
-including jobs and overlapping record IDs. Your app still authorizes users and
-provides the UI. Start with [the mailbox guide](docs/mailboxes.md), and configure
-[tenant connections](docs/activerecord-tenanted.md) before loading models when
-using separate databases. Plain Ruby users do not load this module.
+The included Worker stores incoming email at Cloudflare and retries delivery
+while Rails is unavailable. Rails verifies each request and stores the original
+email through Action Mailbox.
 
-## Durable mailbox delivery from Rails
+[![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)
 
-For a mailbox application, use the optional outbox instead of recreating send
-claims, attempt records, recipient outcomes, and event correlation:
+[Prepare Rails and deploy the Worker](templates/deploy-to-cloudflare/README.md),
+then connect your receiving address in Cloudflare Email Routing.
 
-```sh
-bin/rails generate cloudflare:email:tracking
-bin/rails generate cloudflare:email:outbox
-bin/rails db:migrate
-```
+## Build an inbox
 
-```ruby
-account = Cloudflare::Email::Credentials.account_id
-operation = Cloudflare::Email::ActiveRecord::Outbox.prepare_mail(
-  account_id: account,
-  operation_key: "reply:#{draft.id}:revision:#{draft.revision}",
-  mail: ReplyMailer.reply(draft).message,
-)
-# Enqueue after the transaction that prepared the operation commits.
-Cloudflare::Email::SendJob.perform_later(account, operation.operation_key)
-```
+The [mailbox guide](docs/mailboxes.md) walks through creating inboxes and aliases,
+receiving mail, marking it read, archiving it, and sending replies.
 
-The job sends the stored MIME once per operation claim. Accepted repeats cannot
-resend; uncertain sends remain blocked for audited reconciliation. Each recipient
-has separate acceptance evidence and lifecycle status. `DeliveryEvents` persists,
-deduplicates, correlates, orders, and replays queue events, with transactional
-callbacks for your product records. The reference Rails inbox uses these same
-tables and APIs for compose, replies, approved AI drafts, and recovery.
+Mount the optional [management UI](docs/management-engine.md) to manage mailboxes
+and read messages using your app's login and permissions. It is server-rendered
+and needs no frontend build.
 
-`ReplyMailer`, `draft`, and its revision are application examples. Authorize the
-send before preparation and use a durable job backend. See the [complete outbox
-setup and recovery guide](docs/outbox.md) and [gem/inbox architecture](docs/architecture.md).
-The adapter is opt-in; the plain Ruby client does not load Rails or ActiveRecord.
+For a runnable SQLite example, clone the
+[hello-world Rails app](https://github.com/cole-robertson/cloudflare-email-rails-starter).
 
 ## Plain Ruby
 
@@ -184,250 +85,33 @@ client = Cloudflare::Email::Client.new(
 )
 
 response = client.send(
-  from: { address: "hello@mail.example.com", name: "Example" },
+  from: "hello@mail.example.com",
   to: "you@example.net",
   subject: "Hello",
-  text: "Plain body",
-  html: "<p>HTML body</p>",
-  reply_to: "support@in.example.com",
-)
-response.message_id             # Provider ID when returned; nil on older responses
-response.delivered              # Immediately delivered recipients
-response.queued                 # Recipients queued for later delivery
-response.permanent_bounces      # Recipients that permanently bounced
-response.suppressed_recipients  # Recipients dropped by suppression policy
-```
-
-`to` may be omitted for cc-only or bcc-only mail. Addresses accept strings or `{ address:, name: }` hashes. Attachments use Cloudflare's `content` (base64), `filename`, `type`, `disposition`, and optional `content_id` fields. For full MIME control, use `client.send_raw(from:, recipients:, mime_message:)`.
-
-An HTTP success does not mean every recipient received the message. Inspect the recipient outcome arrays and use [delivery events](docs/delivery-events.md) for later results. The current API reference includes message IDs and suppressed recipients; older responses remain supported.
-
-Cloudflare currently limits ordinary sends to 50 recipients and 5 MiB including attachments; verified destination addresses have a 25 MiB allowance. These limits are enforced by Cloudflare. See [limits](https://developers.cloudflare.com/email-service/platform/limits/) and the [header allowlist](https://developers.cloudflare.com/email-service/reference/headers/).
-
-## Receive through ActionMailbox
-
-Cloudflare Email Routing invokes an Email Worker. The bundled Worker forwards unchanged raw MIME to Rails with a versioned HMAC-SHA256 signature covering the timestamp, SMTP envelope, and body. Rails verifies the signature and a five-minute timestamp window before storing the message in ActionMailbox.
-
-```sh
-bin/rails generate cloudflare:email:install
-```
-
-The interactive installer offers ActionMailbox installation/migrations and a default `MainMailbox`, copies the Worker, and configures ingress in development and production. Add `--all-envs` to include test; configure custom staging environments explicitly. Send-only apps do not need ActionMailbox.
-
-Add the generated ingress secret and an optional management token:
-
-```yaml
-cloudflare:
-  account_id: your-account-id
-  api_token: your-runtime-send-token
-  management_token: your-deployment-token
-  ingress_secret: the-generated-random-secret
-```
-
-Equivalent environment names are `CLOUDFLARE_MANAGEMENT_TOKEN` and `CLOUDFLARE_INGRESS_SECRET`. Keep management credentials in the deployment environment rather than the running application. Credentials stored in the application's Rails credentials are accessible to that application; this gem is not a secret-isolation boundary.
-
-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
-```
-
-Subdomain provisioning checks configured DNS before creating a rule. It never enables the parent apex on behalf of a subdomain. A missing setup or permission fails with instructions. DNS records alone do not prove propagation or live routing; send a real test afterward.
-
-For a zone apex, provisioning may enable Email Routing and its DNS records. Only use this when Cloudflare should handle mail for that apex. `provision_catchall DOMAIN=example.com` changes the **zone-wide** catch-all; a subdomain that resolves to a parent zone is rejected. See [subdomain onboarding](https://developers.cloudflare.com/email-service/configuration/subdomains/).
-
-Replace the scaffolded mailbox's `process` with your application logic. For tenant or mailbox selection, use the authenticated SMTP recipient rather than the sender-controlled MIME `To`/`Cc` headers:
-
-```ruby
-class ApplicationMailbox < ActionMailbox::Base
-  routing ->(inbound) { Cloudflare::Email::Envelope.for(inbound)&.fetch("to")&.match?(/\Asupport@/i) } => :support
-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.
-
-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. 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
-
-For a simple development tunnel, use the explicit direct fallback. Start Rails, then:
-
-```sh
-INBOUND_DELIVERY_MODE=direct bin/rails cloudflare:email:deploy_worker
-bin/rails cloudflare:email:dev
-```
-
-The dev task requires `cloudflared`, refuses environments other than development, and updates the existing development Worker's URL to a temporary tunnel. It forces a dedicated origin Host; development middleware permits only POSTs to the email ingress on that Host. Restart Rails after upgrading: the task checks that the guard is running before opening the tunnel. Configure a separate development receiving address and route. Stopping the tunnel leaves that URL in the development Worker until the next update. A Worker deployed without a URL rejects mail until the tunnel sets it.
-
-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`. Initial durable infrastructure deployment uses Wrangler and requires Node 22.12+ (or a supported newer version):
-
-```sh
-cd cloudflare-worker
-npm ci
-npx wrangler secret put INGRESS_SECRET --env production
-npx wrangler secret put RAILS_INGRESS_URL --env production
-npm run deploy -- --env production
-```
-
-See the [Worker README](templates/worker/README.md). Existing deployments/templates are not automatically migrated; verify routing before switching names.
-
-Rotate the shared ingress secret in Rails and the corresponding Worker during a coordinated deployment. This version has no overlapping-key rotation window; requests can fail while secrets differ.
-
-## Outbound delivery events
-
-The new `DeliveryEvent` and `EventConsumer` APIs consume Cloudflare Email Sending lifecycle events through an HTTP pull queue: delivered, deferred, bounced, failed, rejected, and complained.
-
-```ruby
-consumer = Cloudflare::Email::EventConsumer.new(
-  account_id: ENV.fetch("CLOUDFLARE_ACCOUNT_ID"),
-  api_token: ENV.fetch("CLOUDFLARE_QUEUES_TOKEN"),
-  queue_id: ENV.fetch("CLOUDFLARE_EVENT_QUEUE_ID"),
-  domains: ["mail.example.com"],
+  text: "Hello from Ruby!",
 )
-consumer.poll do |event|
-  DeliveryEventProcessor.call(event) # Your durable, idempotent application handler
-end
-```
-
-Each event is acknowledged only after the handler returns normally. Configure a dedicated queue, subscription, retry policy, and dead-letter queue first. See the complete [Rails and Ruby delivery-event setup](docs/delivery-events.md).
-
-Rails applications can run `bin/rails generate cloudflare:email:tracking` and
-`bin/rails db:migrate` to install optional durable event receipts. The adapter
-commits before ACK, deduplicates account/event IDs, retains unmatched events,
-and replays them with transactional application handlers. It requires explicit
-opt-in; the plain Ruby client stays independent of ActiveRecord.
-
-Shared helpers include `Response#accepted?` (any provider acceptance, not final
-delivery) and `DeliveryEvent#supersedes?(occurred_at:, terminal:)` for ordering
-matched recipient events. See the [architecture guide](docs/architecture.md) for
-what the gem provides and what belongs in the inbox product.
-
-Applications using the outbox can use `DeliveryEvents.record(event)` and
-`DeliveryEvents.replay(account_id:, message_id:)` for built-in correlation and
-recipient-state projection. Applications with their own delivery schema can
-continue to use the lower-level `EventInbox` with an explicit handler.
-
-## Thread correlation
-
-Prefer storing the provider's returned `message_id` with your conversation and correlating inbound `In-Reply-To` / `References` against that record. Correlation does not authenticate the sender or authorize an action.
-
-Use `Cloudflare::Email::MessageId.normalize(value)` to trim whitespace and one enclosing angle-bracket pair without changing the ID's case. The old `SecureMessageId` helper has been removed.
-
-Cloudflare's current [header documentation](https://developers.cloudflare.com/email-service/reference/headers/) describes Message-ID as platform-controlled. **The September 10 live test confirmed that Cloudflare replaced custom signed IDs**, including raw-MIME and ActionMailer sends. Store the provider ID for Cloudflare reply correlation. See [thread correlation](docs/thread-correlation.md) and the [live evidence](docs/verification/2026-09-10-live.md).
-
-## Retry and configuration
-
-`Client.new` options are also accepted by `config.action_mailer.cloudflare_settings`:
-
-| Option | Default |
-|---|---|
-| `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 |
-| `retry_ambiguous` | `false` |
-| `logger` | `nil`, optional `warn` logger |
-
-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`.
-
-## Observability and permissions
-
-Notifications: `cloudflare_email.send` / `send_raw` include `account_id`, `path`, `status`, `message_id`, and all four recipient outcome arrays. `cloudflare_email.ingress` includes `bytes`, `result` (`ok`, `duplicate`, `bad_signature`, `stale`, `too_large`), and the stored `message_id` when available. `cloudflare_email.delivery_event` wraps handler execution with `event_id`, `message_id`, and lifecycle `status`; it does not report queue acknowledgement completion. Instrumentation errors include ActiveSupport's exception metadata.
-
-| Task | Purpose / credentials |
-|---|---|
-| `doctor` | Read diagnostics with runtime token; limited read permissions are reported |
-| `send_test FROM=... TO=...` | Send a real message using runtime send permission |
-| `deploy_worker URL=https://...` | Management token: Workers Scripts Edit |
-| `provision_route ADDRESS=...` | Management token: Zone Read, Email Routing Rules Edit; DNS Read for subdomain checks; routing-settings write permission for apex enablement |
-| `provision_catchall DOMAIN=...` | Same routing management permissions; changes the zone-wide catch-all |
-| `dev` | Management token: Workers Scripts Edit; development only |
-| `consume_events` | Separate Queues Read/Write token, queue ID, configured handler |
-| `deliver OPERATION_KEY=...` | Dispatch a saved outbox operation using sending credentials |
-| `replay_events [MESSAGE_ID=...]` | Replay durable receipts for the configured account |
-| `pending_deliveries` | List prepared or uncertain outbox operations for operator review |
-
-The optional Rails adapter emits `cloudflare_email.outbox_prepare`,
-`cloudflare_email.outbox_send`, and `cloudflare_email.outbox_reconcile` notifications
-with operation identity and resulting state. These do not contain MIME or API
-tokens. A notification is method instrumentation; an enclosing application
-transaction may still roll back. Inspect the durable ledger for authoritative state.
-
-Management tasks fall back to the runtime token if `management_token` is unset. Restrict scopes and accounts to the operations you need. Event consumers use a separate `queues_token` and do not fall back to a send token.
-
-## SMTP alternative
-
-Cloudflare also supports authenticated SMTP. Existing Rails SMTP applications can use it without this gem's delivery method:
-
-```ruby
-config.action_mailer.delivery_method = :smtp
-config.action_mailer.smtp_settings = {
-  address: "smtp.mx.cloudflare.net",
-  port: 465,
-  ssl: true,
-  authentication: :plain,
-  user_name: "api_token",
-  password: ENV.fetch("CLOUDFLARE_SMTP_TOKEN"),
-}
-```
-
-Cloudflare documents Email Sending Edit permission for SMTP, implicit TLS on port 465, and no outbound STARTTLS on 587. See [SMTP documentation](https://developers.cloudflare.com/email-service/api/send-emails/smtp/). Remove the generated `:cloudflare` initializer override if switching to SMTP.
-
-## Development and verification
-
-```sh
-bundle install
-bundle exec rake test
-bundle exec ruby script/verify_package.rb
-BUNDLE_GEMFILE=gemfiles/rails_7_2.gemfile bundle install
-BUNDLE_GEMFILE=gemfiles/rails_7_2.gemfile bundle exec rake test
-cd templates/worker
-npm ci
-npm test
-npm run check
-npm audit
-```
-
-Tests include actual Rails boot/installation, ActionMailbox persistence and mailbox processing, task orchestration, HTTP-mocked API behavior, and Worker unit tests. CI also builds and installs the packaged gem and runs a real local workerd-to-Rails check. Run the latter with:
-
-```sh
-BUNDLE_GEMFILE=gemfiles/local_ingress.gemfile bundle install
-BUNDLE_GEMFILE=gemfiles/local_ingress.gemfile bundle exec ruby script/verify_local_ingress.rb
+response.message_id
+response.accepted?
 ```
 
-Install the Worker tooling first; Node 22+ must be on PATH (or set `NODE_BINARY` to its executable). This uses synthetic mail and temporary loopback services, not a deployed Cloudflare account. The development bundle pins JSON below 3 because current tested Rails versions require its positional-options API.
+Acceptance is the start of delivery. Use [delivery events](docs/delivery-events.md)
+to track delivered messages, bounces, and complaints.
+See the [Ruby API reference](docs/reference.md) for attachments, raw MIME, and configuration.
 
-See the [verification report](docs/verification/2026-09-10.md) for evidence, the historical dogfood inventory, Rebulk integration findings, and remaining live-provider checks.
+## Guides
 
-A subsequent [live verification pass](docs/verification/2026-09-10-live.md) exercised isolated sending, deployed ingress, binary attachments, reply threading, real LLM processing, and delivery-event redelivery/acknowledgement under `test.rebulk.com`. The [follow-up report](docs/verification/2026-09-10-followup.md) covers authenticated recipient routing and draft-review improvements after that run. Temporary cloud resources were removed afterward. No DNS changes or RubyGems publication occurred. These dated reports do not constitute live verification of later changes.
-
-MIT license.
+| Task | Guide |
+| --- | --- |
+| Set up sending, receiving, and tracking | [Rails quickstart](docs/getting-started.md) |
+| Explore the available features | [Feature list](docs/features.md) |
+| Create inboxes and aliases | [Mailboxes](docs/mailboxes.md) |
+| Add mailbox administration | [Management UI](docs/management-engine.md) |
+| Configure addresses and customer subdomains | [Cloudflare domain setup](templates/worker/docs/domain-setup.md) |
+| Save outgoing messages and safely retry jobs | [Outbox](docs/outbox.md) |
+| Track delivery and bounces | [Delivery events](docs/delivery-events.md) |
+| Use separate SQLite databases | [Database tenancy](docs/activerecord-tenanted.md) |
+| Connect a custom receiving endpoint | [Custom ingress](docs/custom-ingress.md) |
+| Diagnose missing mail | [Troubleshooting](docs/troubleshooting.md) |
+| Configure the client and command-line tasks | [Reference](docs/reference.md) |
+
+[Security](SECURITY.md) · [Contributing](CONTRIBUTING.md) · [MIT license](LICENSE.txt)

data/SECURITY.md

@@ -1,9 +1,5 @@
 # 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.
@@ -40,12 +36,8 @@ Do not place secrets or private message data in public issues.
   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.
+  required. Jobs without the required tenant context are rejected.
 - 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/docs/activerecord-tenanted.md

@@ -168,14 +168,3 @@ database. Missing context must continue to fail closed. Your organization's job
 fan-out should enumerate real organizations, not every database file. Applications
 without configured multi-tenancy can keep ordinary system and organization mail
 in their existing single database; this recipe does not enable tenancy by default.
-
-## What is verified
-
-The optional CI job boots a real Rails application with `activerecord-tenanted`, runs the gem's tenant migrations in two SQLite databases, and checks identical numeric IDs remain isolated. It also verifies context restoration, refusal to create unknown tenant databases, and GlobalID's missing/wrong-tenant rejection. Separate integration tests exercise mailbox ingress, sending, jobs, and delivery-event replay.
-
-Run the library-specific smoke test locally with:
-
-```sh
-BUNDLE_GEMFILE=gemfiles/tenanted.gemfile bundle install
-BUNDLE_GEMFILE=gemfiles/tenanted.gemfile bundle exec ruby test/support/activerecord_tenanted.rb
-```

data/docs/custom-ingress.md

@@ -1,7 +1,5 @@
 # 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.
@@ -181,7 +179,7 @@ const headers = await signedEmailHeaders({
 // 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.
+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.
 
 In your Action Mailbox handler, read persisted metadata through the gem:
 
@@ -197,15 +195,3 @@ This reads verified Active Storage metadata, not similarly named MIME headers. A
 **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.