cloudflare-email 0.1.0 → 0.2.0

data/README.md

@@ -1,93 +1,74 @@
 # cloudflare-email
 
-A Ruby gem for [Cloudflare's Email Service](https://blog.cloudflare.com/email-for-agents/)
-(public beta, April 2026). Send mail from Rails via an `ActionMailer` delivery
-method; receive mail via an `ActionMailbox` ingress backed by a shipped
-Cloudflare Email Worker. Works as a plain Ruby client too.
+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.
 
-```ruby
-# Gemfile
-gem "cloudflare-email"
-```
+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.
 
----
+## Start here
 
-## Two independent paths
+**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.
 
-- **Send only** → skip to [Sending mail](#sending-mail). No Node, no Workers.
-- **Send + Receive** → [Receiving mail](#receiving-mail). Ships a pure-Ruby
-  Worker deployer. **No wrangler. No npm. No dashboard clicking.**
-- Want to cryptographically verify replies belong to the right thread? →
-  [Signed replies](#signed-replies).
+| 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 |
+| [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 |
+| [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 |
 
----
+The sections below are the configuration and API reference.
 
-# Sending mail
+## Install and send from Rails
 
-## Setup (3 minutes)
+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:
 
-```sh
-bundle add cloudflare-email
-bin/rails generate cloudflare:email:install --no-inbound
-bin/rails cloudflare:email:doctor              # verify wiring
-TO=you@example.com bin/rails cloudflare:email:send_test
+```ruby
+gem "cloudflare-email", "~> 0.2.0"
 ```
 
-## Credentials — two options
-
-The gem reads config from **Rails credentials first, then env vars**. Pick
-whichever fits your workflow:
-
-**Option A: Rails credentials** (recommended — encrypted, per-env)
-
 ```sh
-bin/rails credentials:edit --environment production
+bundle install
+bin/rails generate cloudflare:email:install --no-inbound
 ```
 
+Add Rails credentials (encrypted, per environment) or environment variables:
+
 ```yaml
 cloudflare:
-  account_id: <your-cloudflare-account-id>
-  api_token:  <email-send-scoped-api-token>
+  account_id: your-account-id
+  api_token: your-email-sending-token
 ```
 
-**Option B: `.env` / environment variables**
-
-```env
-CLOUDFLARE_ACCOUNT_ID=your-account-id
-CLOUDFLARE_API_TOKEN=your-send-scoped-token
+```sh
+export CLOUDFLARE_ACCOUNT_ID=your-account-id
+export CLOUDFLARE_API_TOKEN=your-email-sending-token
 ```
 
-Use `dotenv-rails`, `foreman`, your platform's secret store (Fly, Render,
-Heroku, Kamal) — anything that puts them into `ENV`.
+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).
 
-## Dashboard setup (one-time)
+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.
 
-1. **API token**: `dash.cloudflare.com/profile/api-tokens` → **Create Token** →
-   **Custom Token**. Permission: **Account → Email Sending → Send**. Scope to
-   your specific account.
-2. **Sending Domain**: your zone → **Email** → **Email Sending** → **Sending
-   Domains** → **Add Sending Domain**. Use a subdomain (e.g.
-   `mail.yourdomain.com`), not the apex if you already have Google Workspace
-   there.
-3. **SPF + DMARC** on the apex (DKIM is auto-published by Cloudflare):
-   ```
-   TXT @       v=spf1 include:_spf.mx.cloudflare.net ~all
-   TXT _dmarc  v=DMARC1; p=quarantine; rua=mailto:postmaster@yourdomain.com
-   ```
-4. Wait until the dashboard shows "Verified" before sending (otherwise a vague
-   `email.sending.error.internal_server` 500 comes back).
+Create a token with permission to send for your account, and verify the domain in the dashboard before testing:
 
-## Send mail
+```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 — the `:cloudflare` delivery method is registered
-automatically:
+Standard ActionMailer works:
 
 ```ruby
 class WelcomeMailer < ApplicationMailer
   def welcome(user)
-    mail(to: user.email, from: "hello@mail.yourdomain.com", subject: "Welcome") do |format|
-      format.text { render plain: "Hi #{user.name}" }
-      format.html { render "welcome_html" }
+    mail(from: "hello@mail.example.com", to: user.email, subject: "Welcome") do |format|
+      format.text { render plain: "Hello!" }
     end
   end
 end
@@ -95,427 +76,323 @@ end
 WelcomeMailer.welcome(user).deliver_later
 ```
 
-Attachments, multipart, threading headers, cc/bcc all round-trip through the
-underlying `send_raw` API.
-
-## Plain Ruby (no Rails)
-
-```ruby
-require "cloudflare-email"
-
-client = Cloudflare::Email::Client.new(
-  account_id: ENV["CLOUDFLARE_ACCOUNT_ID"],
-  api_token:  ENV["CLOUDFLARE_API_TOKEN"],
-)
-
-response = client.send(
-  from:    { address: "agent@mail.acme.com", name: "Acme Agent" },
-  to:      "user@example.com",
-  subject: "Hello",
-  text:    "Plain body",
-  html:    "<p>HTML body</p>",
-  reply_to: "thread+abc@mail.acme.com",
-  headers:  { "In-Reply-To" => "<msg-123@acme.com>" },
-  attachments: [{
-    content:  Base64.strict_encode64(File.read("report.pdf")),
-    filename: "report.pdf",
-    type:     "application/pdf",
-  }],
-)
-
-response.success?   # => true
-response.delivered  # => ["user@example.com"]
-response.message_id # => nil (Cloudflare does not return a message ID)
-```
-
-For full MIME control: `client.send_raw(from:, recipients:, mime_message:)`.
+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
 
-# Receiving mail
+**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.
 
-Cloudflare Email Routing delivers inbound mail to an **Email Worker**, not an
-HTTPS webhook — you can't just point it at a URL. This gem ships a Worker
-that signs each message with HMAC-SHA256 and POSTs it to a Rails `ActionMailbox`
-ingress it sets up for you.
+| 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 |
 
-**No wrangler, npm, or Node required.** The Worker is plain JavaScript; the
-gem ships a pure-Ruby deployer that talks directly to Cloudflare's Workers
-API. `wrangler` is supported as an alternative if you prefer the Cloudflare
-CLI.
+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.
 
-## Setup
+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
-bundle add cloudflare-email
-bin/rails generate cloudflare:email:install    # interactive; scaffolds everything
-bin/rails credentials:edit                     # fill in the 4 secrets (below)
-bin/rails cloudflare:email:doctor              # verify
-bin/rails cloudflare:email:deploy_worker URL=https://yourapp.com/rails/action_mailbox/cloudflare/inbound_emails
-bin/rails cloudflare:email:provision_route ADDRESS=cole@in.yourdomain.com
+bin/rails generate cloudflare:email:mailboxes
+bin/rails db:migrate
 ```
 
-That's it. Zero dashboard clicks once your tokens are created.
+After registering and verifying a receiving domain:
 
-The interactive installer:
+```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
+```
 
-1. Copies the Worker template into `cloudflare-worker/` + writes the
-   `config/initializers/cloudflare_email.rb` initializer.
-2. Scaffolds a default `MainMailbox` + catch-all route (prompt) so inbound
-   mail has somewhere to land on day one.
-3. Runs `bin/rails action_mailbox:install` (prompt) if ActionMailbox is
-   missing in the app.
+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.
 
-## Credentials
+## Durable mailbox delivery from Rails
 
-Same two options as sending (credentials OR `.env`). For inbound you need
-three values plus an ingress secret:
+For a mailbox application, use the optional outbox instead of recreating send
+claims, attempt records, recipient outcomes, and event correlation:
 
-```yaml
-cloudflare:
-  account_id:     <your-cloudflare-account-id>
-  api_token:      <runtime token — Email Sending: Send>
-  management_token: <optional; Workers + Email Routing + Zone Read>
-  ingress_secret: <generated by the installer>
+```sh
+bin/rails generate cloudflare:email:tracking
+bin/rails generate cloudflare:email:outbox
+bin/rails db:migrate
 ```
 
-Or via env vars:
-
-```env
-CLOUDFLARE_ACCOUNT_ID=...
-CLOUDFLARE_API_TOKEN=...
-CLOUDFLARE_MANAGEMENT_TOKEN=...   # optional
-CLOUDFLARE_INGRESS_SECRET=...
+```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)
 ```
 
-## Tokens — why two?
+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.
 
-For best security, split your tokens into runtime and management:
+`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.
 
-- **Runtime** (`api_token`): `Email Sending → Send` only. Lives in the app
-  process at runtime. If leaked, attacker can send spam — that's it.
-- **Management** (`management_token`): `Workers Scripts: Edit`, `Zone: Read`,
-  `Email Routing: Edit`. Used by `deploy_worker`, `provision_route`, and
-  `dev` tasks. **Never loaded by the running Rails app** — set it in your
-  deploy environment only, or as a local `.env` for your laptop.
+## Plain Ruby
 
-If only `api_token` is set, management tasks fall back to it. Single-token
-setups are fine for solo devs / small projects; split tokens are strongly
-recommended for production.
-
-## Dashboard setup — one step
-
-Only one dashboard visit needed: create the token(s) at
-`dash.cloudflare.com/profile/api-tokens`. Choose the scopes from the
-[Tokens](#tokens--why-two) table.
-
-Everything else — sending domain, Email Routing enablement, MX records, route
-rules — can be done in the dashboard OR automated from Ruby via the gem's
-rake tasks. See the [rake task reference](#rake-tasks) below.
-
-## Write your mailbox
+```ruby
+require "cloudflare-email"
 
-The installer creates `MainMailbox` with a stub. Replace `#process`:
+client = Cloudflare::Email::Client.new(
+  account_id: ENV.fetch("CLOUDFLARE_ACCOUNT_ID"),
+  api_token: ENV.fetch("CLOUDFLARE_API_TOKEN"),
+)
 
-```ruby
-# app/mailboxes/main_mailbox.rb
-class MainMailbox < ApplicationMailbox
-  def process
-    YourAgentJob.perform_later(
-      from: mail.from.first,
-      subject: mail.subject,
-      body: mail.body.decoded,
-    )
-  end
-end
+response = client.send(
+  from: { address: "hello@mail.example.com", name: "Example" },
+  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
 ```
 
-Route by address or content in `ApplicationMailbox`:
+`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:)`.
 
-```ruby
-class ApplicationMailbox < ActionMailbox::Base
-  routing /^support@/i => :support
-  routing :all         => :main
-end
-```
+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/).
 
-## Local development
+## Receive through ActionMailbox
 
-You need a public HTTPS URL for Cloudflare to POST to. In dev that means
-tunneling. Run `bin/rails server` in one terminal, then:
+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 cloudflare:email:dev
+bin/rails generate cloudflare:email:install
 ```
 
-That task starts a `cloudflared` tunnel, updates your deployed Worker's
-`RAILS_INGRESS_URL` secret to point at it, and ties up the terminal until
-Ctrl-C. Send mail to your routed address; it flows Cloudflare → Worker →
-tunnel → local Rails → your mailbox.
+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.
 
-Only `cloudflared` required — no wrangler, no Node.
+Add the generated ingress secret and an optional management token:
 
-## Per-environment Worker isolation
+```yaml
+cloudflare:
+  account_id: your-account-id
+  api_token: your-runtime-send-token
+  management_token: your-deployment-token
+  ingress_secret: the-generated-random-secret
+```
 
-The gem names the Worker `cloudflare-email-ingress-#{Rails.env}` by default.
-Dev, staging, and prod deploy as **separate scripts** with separate secrets.
-`bin/rails cloudflare:email:dev` only ever touches `-development`, so spinning
-up a dev tunnel can never break production's inbound.
+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.
 
-Deploy per environment:
+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:
 
 ```sh
-RAILS_ENV=production  bin/rails cloudflare:email:deploy_worker URL=https://app.example.com/rails/action_mailbox/cloudflare/inbound_emails
-RAILS_ENV=staging     bin/rails cloudflare:email:deploy_worker URL=https://staging.example.com/rails/action_mailbox/cloudflare/inbound_emails
+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
 ```
 
-Route different addresses to different Workers:
+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.
 
-```sh
-RAILS_ENV=production bin/rails cloudflare:email:provision_route ADDRESS=cole@in.yourdomain.com
-RAILS_ENV=staging    bin/rails cloudflare:email:provision_route ADDRESS=cole@staging.in.yourdomain.com
-```
+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/).
 
-## ⚠️ Apex vs subdomain
+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:
 
-**Don't enable Email Routing on the apex** of a domain where colleagues run
-email on Google Workspace or Outlook — MX records are domain-level, so
-that'd route everyone's mail through Cloudflare first. Use a subdomain
-(`in.yourdomain.com`).
+```ruby
+class ApplicationMailbox < ActionMailbox::Base
+  routing ->(inbound) { Cloudflare::Email::Envelope.for(inbound)&.fetch("to")&.match?(/\Asupport@/i) } => :support
+end
+```
 
-If you want your own `cole@yourdomain.com` to also reach the agent, set up a
-Google Workspace routing rule that BCCs incoming mail to
-`cole@in.yourdomain.com`. You read mail in Gmail normally AND the agent
-gets a copy.
+`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.
 
-## Rotating the ingress secret
+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.
 
-Rotate Worker and Rails together (no overlap window):
+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.
 
-1. `bin/rails credentials:edit` — update `cloudflare.ingress_secret`.
-2. Re-run `bin/rails cloudflare:email:deploy_worker URL=...` to push the new
-   secret to the Worker + redeploy.
+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.
 
-If they disagree, inbound mail bounces with 401 and the sender gets a
-delivery failure (no silent drop).
+### Local development and deployment
 
-## How inbound flows
+Start Rails, then:
 
-```
-Sender's MTA
-     │  MX lookup resolves to Cloudflare
-     ▼
-Cloudflare Email Routing
-     │  (rule matched, action = "Send to Worker")
-     ▼
-cloudflare-email-ingress-{env} Worker  (reads message.raw, HMAC-signs)
-     │  POST with Content-Type: message/rfc822
-     │  + X-CF-Email-Timestamp + X-CF-Email-Signature
-     ▼
-Your Rails app — IngressController
-     │  (verifies HMAC, 5-min replay window)
-     ▼
-ActionMailbox::InboundEmail.create_and_extract_message_id!
-     │
-     ▼
-ApplicationMailbox → YourMailbox#process
+```sh
+bin/rails cloudflare:email:deploy_worker
+bin/rails cloudflare:email:dev
 ```
 
-If Rails responds non-2xx, the Worker calls `message.setReject` so the sender
-gets a bounce. No silent drops.
+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.
 
-# Signed replies
+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):
 
-Optional but **highly recommended** for agent email flows: cryptographically
-bind replies to the original thread so the inbound side can prove a reply
-is legitimate and hasn't been forged. Inspired by Cloudflare's
-[`createSecureReplyEmailResolver`](https://developers.cloudflare.com/agents/api-reference/email/)
-from the JS Agents SDK, but stateless — no Durable Object storage needed.
+```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
+```
 
-**How it works**: sign the outbound `Message-ID:` with HMAC-SHA256. When a
-user replies, their mail client naturally carries the original id into the
-`In-Reply-To:` header. Your mailbox reads + verifies it there, recovers the
-payload (thread id, user id, whatever you encoded), and routes accordingly.
+See the [Worker README](templates/worker/README.md). Existing deployments/templates are not automatically migrated; verify routing before switching names.
 
-- HMAC-SHA256, 30-day default max-age (configurable)
-- Stateless — no DB row to look up, no Durable Object
-- No catch-all route required — replies come to your normal inbound address
-- User-visible reply-to address stays clean (`agent@in.yourdomain.com`)
-- No size constraint on payloads — Message-IDs can be ~900 chars
+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
+## Outbound delivery events
 
-```ruby
-class AgentMailer < ApplicationMailer
-  def ping(thread)
-    signed_id = Cloudflare::Email::SecureMessageId.encode(
-      payload: {
-        thread_id: thread.id,
-        user_id:   thread.user_id,
-        kind:      "ping",
-      },
-      domain: "mail.yourdomain.com",
-      secret: Rails.application.credentials.dig(:cloudflare, :reply_secret),
-    )
-
-    mail(
-      to:         thread.user.email,
-      from:       "agent@mail.yourdomain.com",
-      reply_to:   "agent@in.yourdomain.com",   # clean, routable address
-      subject:    "Re: #{thread.title}",
-      message_id: signed_id,                    # sign the Message-ID
-    ) { |f| f.text { render plain: "..." } }
-  end
-end
-```
-
-## Inbound
+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
-class AgentMailbox < ApplicationMailbox
-  def process
-    ref = mail.in_reply_to || Array(mail.references).first
-    if ref && Cloudflare::Email::SecureMessageId.match?(ref)
-      payload = Cloudflare::Email::SecureMessageId.decode(
-        ref,
-        secret: Rails.application.credentials.dig(:cloudflare, :reply_secret),
-      )
-      Thread.find(payload["thread_id"]).ingest(mail)
-    end
-  rescue Cloudflare::Email::SecureMessageId::InvalidToken => e
-    Rails.logger.warn("Invalid signed reply: #{e.message}")
-  end
+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"],
+)
+consumer.poll do |event|
+  DeliveryEventProcessor.call(event) # Your durable, idempotent application handler
 end
 ```
 
-Route replies to `agent@in.yourdomain.com` normally (`provision_route`).
-The signed state rides in the Message-ID, not the recipient address.
-
-## Setup
-
-Add a reply secret to credentials:
-
-```yaml
-cloudflare:
-  reply_secret: <openssl rand -hex 32>
-```
-
-(Or `CLOUDFLARE_REPLY_SECRET` in your env.)
+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).
 
-That's it. Use the helpers in your mailer + mailbox as shown above.
+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.
 
-## Compared to Cloudflare's JS SDK
+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.
 
-| | Our `SecureMessageId` | CF `createSecureReplyEmailResolver` |
-|---|---|---|
-| Signing | HMAC-SHA256 (full 64-char hex) | HMAC-SHA256 (full) |
-| Carrier | `Message-ID:` → `In-Reply-To:` | Headers + Durable Object lookup |
-| Statefulness | Stateless | Stateful (DO storage) |
-| Works in plain Rails | Yes | Requires Workers + DO |
+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.
 
-Same security properties (HMAC-SHA256, time-boxed with max-age), different
-mechanism. `SecureMessageId` is the idiomatic Rails choice — stateless,
-size-unconstrained, and matches email threading natively.
+## 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.
 
-# Rake tasks + token scopes
+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.
 
-| Task | What it does | Token scopes |
-|---|---|---|
-| `doctor` | Verifies credentials, API token validity, ingress secret, `ActionMailbox.ingress`, delivery method. Exit 1 on failure. | `Email Sending: Send` |
-| `send_test TO=addr [FROM=addr]` | One-shot test send. FROM auto-detected from verified sending domains. | `Email Sending: Send` |
-| `deploy_worker URL=https://...` | Uploads the Worker + sets `INGRESS_SECRET` + `RAILS_INGRESS_URL`. Pure Ruby, no wrangler. Targets `cloudflare-email-ingress-#{Rails.env}`. | `Workers Scripts: Edit` |
-| `provision_route ADDRESS=addr@domain` | Creates/updates an Email Routing rule binding the address to the env-scoped Worker. Idempotent. | `Zone: Read`, `Email Routing: Edit` |
-| `provision_catchall DOMAIN=sub.domain` | Points the zone's catch-all rule at the env-scoped Worker. | `Zone: Read`, `Email Routing: Edit` |
-| `dev` | Starts a `cloudflared` tunnel, auto-updates the `-development` Worker's `RAILS_INGRESS_URL` to point at it. | `Workers Scripts: Edit` |
+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).
 
-Create tokens at `dash.cloudflare.com/profile/api-tokens` → **Custom Token**.
-Scope to a single account. For production, use two tokens: a runtime
-(`Email Sending: Send` only) and a management (everything else).
+## Retry and configuration
 
----
+`Client.new` options are also accepted by `config.action_mailer.cloudflare_settings`:
 
-# Reference
-
-## Configuration
-
-| Setting | Default | Notes |
-|---|---|---|
-| `account_id` | — | Required. |
-| `api_token` | — | Required. `Email Sending: Send` permission. |
-| `base_url` | `https://api.cloudflare.com/client/v4` | Override for testing. |
-| `retries` | `3` | On 429 / 5xx / network errors. |
-| `initial_backoff` | `0.5` | Seconds. Doubles each retry. |
-| `max_retry_after` | `60` | Upper bound on `Retry-After` sleep. |
-| `timeout` | `30` | Seconds. Open + read. |
-| `logger` | `nil` | Responds to `#warn`. Logs retries. |
+| Option | Default |
+|---|---|
+| `account_id`, `api_token` | Required |
+| `base_url` | `https://api.cloudflare.com/client/v4` |
+| `timeout` | 30 seconds for open/read/write |
+| `retries` | 3 additional attempts |
+| `initial_backoff` | 0.5 seconds, doubling |
+| `max_retry_after` | 60 seconds |
+| `retry_ambiguous` | `false` |
+| `logger` | `nil`, optional `warn` logger |
 
-In Rails: `config.action_mailer.cloudflare_settings = { ... }`.
+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.
 
-## Retry, rate limit, idempotency
+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.
 
-- Retries on 429, 5xx, and network errors with exponential backoff.
-- `Retry-After` on 429 is honored, capped at `max_retry_after`.
-- **Cloudflare does not accept an idempotency key** and does not return a
-  `message_id` in send responses. Dedupe on your side via the outbound
-  `Message-ID` header if you care about exactly-once semantics.
+Errors inherit from `Cloudflare::Email::Error`: `ConfigurationError`, `AuthenticationError`, `ValidationError`, `RateLimitError`, `ServerError`, and `NetworkError`. API errors expose `status` and parsed `response`.
 
-## Errors
+## Observability and permissions
 
-All descend from `Cloudflare::Email::Error`:
+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.
 
-| Class | Trigger |
+| Task | Purpose / credentials |
 |---|---|
-| `ConfigurationError` | Bad init arguments |
-| `AuthenticationError` | 401 / 403 |
-| `ValidationError` | 400 / 422 or bad input |
-| `RateLimitError` | 429 (retried first) |
-| `ServerError` | 5xx (retried first) |
-| `NetworkError` | Connection failure (retried first) |
-| `SecureMessageId::InvalidToken` | Signature mismatch, expired, malformed |
+| `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 |
 
-Each carries `#status` and `#response` (parsed error body).
+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.
 
-## Observability
+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.
 
-Subscribe to `ActiveSupport::Notifications`:
+## SMTP alternative
 
-```ruby
-ActiveSupport::Notifications.subscribe("cloudflare_email.send_raw") do |event|
-  Rails.logger.info("cf_email status=#{event.payload[:status]} duration=#{event.duration.round(1)}ms")
-end
+Cloudflare also supports authenticated SMTP. Existing Rails SMTP applications can use it without this gem's delivery method:
 
-ActiveSupport::Notifications.subscribe("cloudflare_email.ingress") do |event|
-  StatsD.increment("cf_email.ingress", tags: ["result:#{event.payload[:result]}"])
-end
+```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"),
+}
 ```
 
-| Event | Payload keys |
-|---|---|
-| `cloudflare_email.send` | `:account_id`, `:path`, `:status`, `:message_id` (nil) |
-| `cloudflare_email.send_raw` | `:account_id`, `:path`, `:status`, `:message_id` (nil) |
-| `cloudflare_email.ingress` | `:bytes`, `:result` (`:ok` / `:bad_signature` / `:stale`), `:message_id` when `:ok` |
+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.
 
-## Testing the gem itself
+## Development and verification
 
 ```sh
+bundle install
 bundle exec rake test
-# Against a specific Rails:
-BUNDLE_GEMFILE=gemfiles/rails_7_1.gemfile bundle exec rake test
-# Worker tests:
-cd templates/worker && npm install --legacy-peer-deps && npm 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
 ```
 
-## Status
+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.
 
-**v0.1**. Ruby 3.1+, Rails 7.1 / 7.2 / 8.0 / 8.1. Cloudflare Email Service
-is itself in public beta. Verified against live Cloudflare end-to-end for
-outbound, inbound, Worker deploy, route provisioning, and signed-Message-ID
-reply auth. Issues and PRs welcome.
+See the [verification report](docs/verification/2026-09-10.md) for evidence, the historical dogfood inventory, Rebulk integration findings, and remaining live-provider checks.
 
-## License
+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.
+MIT license.