cloudflare-email 0.2.0 → 0.4.0

data/lib/cloudflare/email/worker_deployer.rb

@@ -55,12 +55,20 @@ module Cloudflare
 
       # Uploads/updates the Worker script. Accepts either `script_path:` (a
       # path to a .js file) or `source:` (the JS source string directly).
-      def deploy(script_path: nil, source: nil)
+      # The Rails deploy task passes delivery_mode: "durable" and validates
+      # existing infrastructure. Low-level callers managing custom Workers may
+      # omit it to preserve their configured transport without changing it.
+      def deploy(script_path: nil, source: nil, delivery_mode: nil)
         source ||= File.read(script_path) if script_path
         raise ArgumentError, "must pass script_path: or source:" if source.nil?
 
+        if delivery_mode
+          raise ArgumentError, "delivery_mode must be durable or direct" unless %w[durable direct].include?(delivery_mode)
+          verify_durable_infrastructure! if delivery_mode == "durable"
+        end
+
         boundary = "----cf-email-#{SecureRandom.hex(16)}"
-        body     = build_multipart(boundary, source)
+        body     = build_multipart(boundary, source, delivery_mode)
 
         request(
           method: :put,
@@ -108,11 +116,34 @@ module Cloudflare
 
       private
 
-      def build_multipart(boundary, source)
-        metadata = JSON.generate({
+      def verify_durable_infrastructure!
+        settings = request(method: :get, path: "/accounts/#{@account_id}/workers/scripts/#{@script_name}/settings")
+        bindings = Array(settings.dig("result", "bindings"))
+        configured = bindings.any? { |b| b["name"] == "INBOUND_EMAIL_STORE" && b["type"] == "r2_bucket" } &&
+          bindings.any? { |b| b["name"] == "INBOUND_EMAIL_QUEUE" && b["type"] == "queue" }
+        schedules = request(method: :get, path: "/accounts/#{@account_id}/workers/scripts/#{@script_name}/schedules")
+        configured &&= Array(schedules.dig("result", "schedules")).any? { |s| s["cron"] == "* * * * *" }
+        return if configured
+
+        raise ConfigurationError, "Provision durable R2, Queue producer/consumer and minute schedule using the generated Worker docs/durable-inbound.md before deploying; use INBOUND_DELIVERY_MODE=direct only for explicit direct fallback"
+      rescue Error => error
+        raise unless error.status == 404
+
+        raise ConfigurationError, "Provision the durable Worker with Wrangler first (see Worker docs/durable-inbound.md); use INBOUND_DELIVERY_MODE=direct only for explicit direct fallback"
+      end
+
+      def build_multipart(boundary, source, delivery_mode)
+        settings = {
           main_module:        "index.js",
           compatibility_date: @compatibility_date,
-        })
+          # API script uploads must not remove provisioned storage, queue or
+          # secrets. In particular a direct rollback still drains pending mail.
+          keep_bindings: %w[secret_text plain_text r2_bucket queue],
+        }
+        if delivery_mode
+          settings[:bindings] = [{ type: "plain_text", name: "INBOUND_DELIVERY_MODE", text: delivery_mode }]
+        end
+        metadata = JSON.generate(settings)
 
         parts = []
         parts << "--#{boundary}"

data/lib/cloudflare-email.rb

@@ -1,3 +1,9 @@
+require "mailbox-kit"
+module Cloudflare
+  module Email
+    Mailboxes = MailboxKit::Mailboxes
+  end
+end
 require "cloudflare/email/version"
 require "cloudflare/email/error"
 require "cloudflare/email/response"

data/lib/generators/cloudflare/email/install_generator.rb

@@ -102,8 +102,8 @@ module Cloudflare
           should_deploy = options[:deploy_worker]
           if should_deploy.nil?
             say ""
-            say "  The Worker can be deployed via the Cloudflare API (pure Ruby, no wrangler/Node)"
-            say "  once you've set cloudflare.account_id and cloudflare.api_token in Rails credentials."
+            say "  First provision durable storage, Queue and cron using the generated Worker docs/durable-inbound.md."
+            say "  After the initial Wrangler deploy, Ruby uploads preserve those infrastructure bindings."
             say "  Run `RAILS_ENV=production bin/rails cloudflare:email:deploy_worker SCRIPT=#{worker_script_argument} URL=https://yourapp.com#{ingress_path}`"
             say "  after `bin/rails credentials:edit`."
             say ""
@@ -121,6 +121,7 @@ module Cloudflare
             @ingress_secret = SecureRandom.hex(32)
 
             inside options[:worker_dir] do
+              say "Create the R2 bucket and Queue in docs/durable-inbound.md before deploying. Customize wrangler.toml names if needed."
               run "npm ci", abort_on_failure: true
 
               ingress_url = ask("Rails ingress URL? (e.g. https://yourapp.com#{ingress_path})")
@@ -168,10 +169,10 @@ module Cloudflare
 
           if options[:inbound] && !@worker_deployed
             say "  4. Deploy the Worker (pick one):"
-            say "       # Pure Ruby (recommended — no wrangler/Node required):"
+            say "       # First follow Worker docs/durable-inbound.md to provision R2, Queue and cron."
             say "       RAILS_ENV=production bin/rails cloudflare:email:deploy_worker SCRIPT=#{worker_script_argument} URL=https://yourapp.com#{ingress_path}"
             say ""
-            say "       # Or via wrangler if you have it installed:"
+            say "       # Initial infrastructure deploy (after provisioning resources):"
             say "       cd #{options[:worker_dir]}"
             say "       npm ci"
             say "       npm run deploy -- --env production"
@@ -182,7 +183,7 @@ module Cloudflare
 
           if options[:inbound]
             say "  5. For local dev (tunnels cloudflared to your Worker):"
-            say "       RAILS_ENV=development bin/rails cloudflare:email:deploy_worker SCRIPT=#{worker_script_argument}"
+            say "       INBOUND_DELIVERY_MODE=direct RAILS_ENV=development bin/rails cloudflare:email:deploy_worker SCRIPT=#{worker_script_argument}"
             say "       RAILS_ENV=development bin/rails cloudflare:email:dev"
             say "     Route a separate test address to cloudflare-email-ingress-development."
             say ""

data/lib/generators/cloudflare/email/mailboxes/catch_all/catch_all_generator.rb

@@ -0,0 +1,21 @@
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Cloudflare
+  module Email
+    module Generators
+      class CatchAllGenerator < ::Rails::Generators::Base
+        include ::ActiveRecord::Generators::Migration
+        namespace "cloudflare:email:mailboxes:catch_all"
+        source_root File.expand_path("templates", __dir__)
+        class_option :tenant_migrations_path, type: :string, default: "db/migrate",
+          desc: "Migration directory applied to every tenant database"
+
+        def copy_migration
+          migration_template "add_cloudflare_email_catch_all.rb",
+            File.join(options[:tenant_migrations_path], "add_cloudflare_email_catch_all.rb")
+        end
+      end
+    end
+  end
+end

data/lib/generators/cloudflare/email/mailboxes/catch_all/templates/add_cloudflare_email_catch_all.rb

@@ -0,0 +1,18 @@
+class AddCloudflareEmailCatchAll < ActiveRecord::Migration[7.1]
+  def up
+    unless column_exists?(:cloudflare_email_addresses, :catch_all)
+      add_column :cloudflare_email_addresses, :catch_all, :boolean, null: false, default: false
+    end
+    unless column_exists?(:cloudflare_email_addresses, :catch_all_evidence)
+      add_column :cloudflare_email_addresses, :catch_all_evidence, :text
+    end
+    unless index_exists?(:cloudflare_email_addresses, :receiving_domain_id, name: "idx_cf_email_domain_catch_all")
+      add_index :cloudflare_email_addresses, :receiving_domain_id, unique: true,
+        where: "catch_all = TRUE AND state = 'active'", name: "idx_cf_email_domain_catch_all"
+    end
+  end
+
+  def down
+    raise ActiveRecord::IrreversibleMigration, "Disable catch-all receiving before an explicit forward schema change"
+  end
+end

data/lib/generators/cloudflare/email/mailboxes/templates/create_cloudflare_email_mailboxes.rb

@@ -19,10 +19,14 @@ class CreateCloudflareEmailMailboxes < ActiveRecord::Migration[7.1]
       t.string :address, null: false
       t.string :state, null: false, default: "pending"
       t.text :provisioning_evidence
+      t.boolean :catch_all, null: false, default: false
+      t.text :catch_all_evidence
       t.timestamps
     end
     add_index :cloudflare_email_addresses, :address, unique: true, name: "idx_cf_email_mailbox_address"
     add_index :cloudflare_email_addresses, :mailbox_id, name: "idx_cf_email_address_mailbox"
+    add_index :cloudflare_email_addresses, :receiving_domain_id, unique: true,
+      where: "catch_all = TRUE AND state = 'active'", name: "idx_cf_email_domain_catch_all"
 
     create_table :cloudflare_email_mailbox_messages do |t|
       t.string :tenant_key, null: false
@@ -36,6 +40,7 @@ class CreateCloudflareEmailMailboxes < ActiveRecord::Migration[7.1]
       t.timestamps
     end
     add_index :cloudflare_email_mailbox_messages, [:mailbox_id, :inbound_email_id], unique: true, name: "idx_cf_email_mailbox_inbound"
+    add_index :cloudflare_email_mailbox_messages, :inbound_email_id, name: "idx_cf_email_message_inbound"
     add_index :cloudflare_email_mailbox_messages, [:tenant_key, :mailbox_id, :archived_at, :id], name: "idx_cf_email_mailbox_inbox"
 
     create_table :cloudflare_email_mailbox_outbound_messages do |t|

data/lib/generators/cloudflare/email/mailboxes/templates/create_cloudflare_email_receiving_domains.rb

@@ -3,7 +3,7 @@ class CreateCloudflareEmailReceivingDomains < ActiveRecord::Migration[7.1]
     create_table :cloudflare_email_receiving_domains do |t|
       t.string :domain, null: false
       t.string :tenant_key, null: false
-      t.string :account_id, null: false
+      t.string :account_id # Required by the sending adapter only.
       t.string :state, null: false, default: "pending"
       t.boolean :sending_enabled, null: false, default: false
       t.text :provisioning_evidence

data/lib/generators/cloudflare/email/routing_tracking/routing_tracking_generator.rb

@@ -0,0 +1,28 @@
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Cloudflare
+  module Email
+    module Generators
+      class RoutingTrackingGenerator < ::Rails::Generators::Base
+        include ::ActiveRecord::Generators::Migration
+        namespace "cloudflare:email:routing_tracking"
+        source_root File.expand_path("templates", __dir__)
+        class_option :migrations_path, type: :string, default: "db/migrate"
+
+        def copy_tracking_migration
+          migration_template "create_cloudflare_email_routing_delivery_receipts.rb",
+            File.join(options[:migrations_path], "create_cloudflare_email_routing_delivery_receipts.rb")
+        end
+
+        def create_initializer
+          create_file "config/initializers/cloudflare_email_routing_tracking.rb", <<~RUBY
+            # Requires the outbox migration and Rails Active Record encryption keys.
+            # This loads the API only; your application schedules analytics polling.
+            require "cloudflare/email/active_record/routing_deliveries"
+          RUBY
+        end
+      end
+    end
+  end
+end

data/lib/generators/cloudflare/email/routing_tracking/templates/create_cloudflare_email_routing_delivery_receipts.rb

@@ -0,0 +1,22 @@
+class CreateCloudflareEmailRoutingDeliveryReceipts < ActiveRecord::Migration[7.1]
+  def up
+    create_table :cloudflare_email_routing_delivery_receipts do |t|
+      t.references :outbound_delivery, null: false, index: {name: "idx_cf_routing_delivery"},
+        foreign_key: {to_table: :cloudflare_email_outbound_deliveries}
+      t.string :account_id, null: false
+      t.string :zone_id, null: false
+      t.string :event_key, null: false
+      t.text :payload_json, null: false
+      t.string :state, null: false, default: "pending"
+      t.datetime :received_at, null: false
+      t.datetime :applied_at
+      t.timestamps
+    end
+    add_index :cloudflare_email_routing_delivery_receipts, [:account_id, :event_key], unique: true, name: "idx_cf_routing_identity"
+    add_index :cloudflare_email_routing_delivery_receipts, [:account_id, :state, :id], name: "idx_cf_routing_replay"
+  end
+
+  def down
+    raise ActiveRecord::IrreversibleMigration, "Preserve authentic delivery evidence; use a forward fix or a reconciled backup"
+  end
+end

data/lib/tasks/cloudflare_email.rake

@@ -15,7 +15,8 @@ namespace :cloudflare do
     desc "Deploy the Worker via Cloudflare API. URL=https://... sets RAILS_INGRESS_URL; SCRIPT=path overrides the Worker source"
     task deploy_worker: :environment do
       require "cloudflare/email/deploy_worker_task"
-      exit Cloudflare::Email::DeployWorkerTask.call(ingress_url: ENV["URL"], script_path: ENV["SCRIPT"])
+      exit Cloudflare::Email::DeployWorkerTask.call(ingress_url: ENV["URL"], script_path: ENV["SCRIPT"],
+        delivery_mode: ENV.fetch("INBOUND_DELIVERY_MODE", "durable"))
     end
 
     desc "Create Cloudflare Email Routing rule: ADDRESS=addr@domain → env-scoped Worker (WORKER=name to override)"

data/lib/tasks/cloudflare_email_diagnostics.rake

@@ -0,0 +1,11 @@
+namespace :cloudflare do
+  namespace :email do
+    desc "Inspect routing without changes (ADDRESS=addr [WORKER_NAME=name] [ACCOUNT_ID=id]); nonzero if failed or unverified"
+    task check_route: :environment do
+      require "cloudflare/email/check_route_task"
+      exit Cloudflare::Email::CheckRouteTask.call(
+        address: ENV["ADDRESS"], worker_name: ENV["WORKER_NAME"] || ENV["WORKER"], account_id: ENV["ACCOUNT_ID"],
+      )
+    end
+  end
+end

data/templates/deploy-to-cloudflare/.dev.vars.example

@@ -0,0 +1,3 @@
+# Supply these in the Cloudflare deployment form. Never commit real values.
+RAILS_INGRESS_URL=
+INGRESS_SECRET=

data/templates/deploy-to-cloudflare/.gitignore

@@ -0,0 +1,6 @@
+node_modules/
+.wrangler/
+.dev.vars*
+!.dev.vars.example
+.env*
+!.env.example

data/templates/deploy-to-cloudflare/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cole
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/templates/deploy-to-cloudflare/README.md

@@ -0,0 +1,104 @@
+# Cloudflare Email for Rails
+
+Receive email in Rails with the [cloudflare-email gem](https://github.com/cole-robertson/cloudflare-email).
+This template stores inbound mail in private R2, delivers it through a Queue,
+and retries from storage when Rails is unavailable. It includes scheduled
+recovery and Worker logs. No React app or extra server is needed.
+
+[![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)
+
+## 1. Prepare Rails
+
+Install `gem "cloudflare-email", "~> 0.3.0"` and follow the
+[Rails setup guide](https://github.com/cole-robertson/cloudflare-email/blob/main/docs/getting-started.md).
+Deploy Rails with Action Mailbox storage and routing configured before connecting
+real email. Generate a secret with `openssl rand -hex 32` and configure it as
+`cloudflare.ingress_secret` in Rails credentials or `CLOUDFLARE_INGRESS_SECRET`.
+Keep the same value for the deployment form.
+
+## 2. Deploy the Worker
+
+Click the button and sign in to Cloudflare and GitHub/GitLab as prompted.
+Cloudflare copies this directory into your own repository, provisions the R2
+bucket and Queue, and builds the Worker. Enter:
+
+- **RAILS_INGRESS_URL:** your public HTTPS endpoint, normally
+  `https://your-app.com/rails/action_mailbox/cloudflare/inbound_emails`.
+- **INGRESS_SECRET:** the exact secret you configured in Rails.
+
+Choose distinct Worker, bucket, and Queue names for each app/environment. This
+template has one environment per deployment; deploy separate copies for staging
+and production. R2 and Queues must be available on your account and their usage
+can incur charges. Review Cloudflare's resource and billing prompts.
+
+The form uses `npm run deploy`; no `--env` argument is required for this template.
+After deployment, confirm both bindings, the Queue consumer, and the once-per-minute
+cron are present. Keep the bucket private with no lifecycle rule expiring
+`cloudflare-email/pending/` objects. The Worker has no public email-submit HTTP API.
+
+## 3. Connect an email address
+
+**Choose your address shape:** `acme@in.example.com` on one receiving domain,
+or `invoices@acme.in.example.com` with dynamic organization subdomains.
+Use the [shared domain setup guide](docs/domain-setup.md) for the setup worksheet,
+Cloudflare DNS/routing steps, cited Rebulk example, and verification commands.
+The same Worker serves both; there is no per-organization Worker allowlist.
+
+In Cloudflare, enable Email Routing for the intended receiving domain/subdomain
+and complete its required DNS setup. Add an Email Routing rule for your receiving
+address with **Send to a Worker**, selecting the Worker you just deployed. For
+many local parts, configure the intended domain's catch-all to this Worker once.
+The button does not change your MX records, provision addresses in Rails, or
+replace your existing mailbox provider. Use a receiving subdomain when your apex
+domain's email belongs to Google Workspace or Microsoft 365.
+
+If using the gem's managed mailboxes, register the receiving mailbox/address in
+Rails too. Tenant support and domain catch-all receiving remain explicit choices.
+After verifying a dynamic namespace as described in the guide, register new
+organization domains in Rails without routinely adding provider rules per org.
+Wildcard DNS behavior must be verified on your Cloudflare account; the guide
+distinguishes working Rebulk evidence from Cloudflare's explicit onboarding docs.
+Outbound Email Sending credentials and delivery-event subscriptions are separate
+from this inbound Worker setup.
+
+## 4. Verify and operate
+
+For dynamic organization subdomains, start with the read-only DNS check:
+
+```sh
+npm run check:subdomains -- --base in.example.com --labels acme,globex
+```
+
+It checks named and fresh labels without API credentials or configuration changes.
+It reports DNS observations only; finish with the real-email checks below.
+
+Send to the configured address and verify that Rails retains and routes it.
+In staging, stop Rails, send another message, confirm it remains in R2, restore
+Rails, and confirm one inbox record and removal of the pending object. Verify a
+retry does not duplicate application work. Monitor Worker errors and pending R2
+count/age; Queue depth alone misses mail whose queue retries are exhausted.
+
+Read the [durable delivery and recovery guide](https://github.com/cole-robertson/cloudflare-email/blob/main/templates/worker/docs/durable-inbound.md)
+for recovery limits, retention, failure drills, and the explicit direct fallback.
+In this standalone template, configure bindings at the top level and run
+`npm run deploy` without `--env`. Do not remove storage or cron while mail is pending.
+Delivery is at least once, with Rails deduplication; application handlers must
+also tolerate retries. Configure operational alerts in your monitoring service.
+
+## Updates and local development
+
+Your copied repository belongs to you; gem updates do not update its Worker
+automatically. Review upstream release notes, deploy Rails first, then port Worker
+changes into your copy while preserving your resource names, secrets, and pending
+storage. Keep production resources separate from test resources.
+
+Use Node 22.12+ (or a supported newer version): `npm ci`, `npm test`, and
+`npm run check`. For local development, copy `.dev.vars.example` to `.dev.vars`,
+set local values, and run `npm run dev`. Never commit secrets.
+
+Upstream maintainers: `templates/worker` is the canonical runtime. Run
+`node script/sync_deploy_template.mjs` from the gem repository after modifying its
+runtime, tests, dependencies, or production bindings. CI rejects drift and tests
+this directory after copying it outside the repository, matching Cloudflare's
+subdirectory deployment model. Edit this README directly; generated files are
+marked by the sync script's file list.

data/templates/deploy-to-cloudflare/docs/domain-setup.md

@@ -0,0 +1,198 @@
+# Set up once, create mailboxes in Rails
+
+Use the same Worker for either address shape:
+
+| Pattern | Example | What changes when a customer joins |
+| --- | --- | --- |
+| One receiving domain | `acme@in.example.com` | Create a mailbox/address in Rails |
+| Organization subdomains | `invoices@acme.in.example.com` | Register the exact organization domain and its mailboxes in Rails, within your verified receiving namespace |
+
+Neither pattern needs a recipient allowlist in the Worker. Rails owns accepted
+addresses and organization membership. Database multi-tenancy remains optional.
+The [Rails hello-world template](https://github.com/cole-robertson/cloudflare-email-rails-starter)
+demonstrates the first pattern with a normal SQLite database and generated login.
+
+## What is verified, and what Cloudflare documents
+
+**Rebulk's existing deployment uses the second pattern:**
+`<site>@<organization>.rebulk.com`, wildcard MX, a catch-all Worker rule, and Rails
+organization/mailbox lookup. New organizations do not need a Worker enrollment
+list or a routine per-organization Cloudflare approval. Its September 2026
+rehearsal checked exact-domain public MX answers and archived SMTP-envelope
+delivery evidence, alongside the global catch-all rule. The apex keeps its
+separate mail provider. Sources (Rebulk repository access required):
+
+- [Worker architecture and organization setup](https://github.com/Rebulk/rebulk-system/blob/1cc26e0076ba0e9157e89f5879604df8c94430bc/cloudflare/README.md).
+- [Wildcard MX observations and limits of zone-level API evidence](https://github.com/Rebulk/rebulk-system/blob/1cc26e0076ba0e9157e89f5879604df8c94430bc/docs/cloudflare-mailbox-onboarding-rehearsal-2026-09-12.md).
+
+This is deployment evidence, not a Cloudflare-wide service guarantee. Cloudflare's
+[subdomain onboarding guide](https://developers.cloudflare.com/email-service/configuration/subdomains/)
+describes adding subdomains explicitly and currently lists a 30-domain combined
+Routing/Sending limit. It does not document arbitrary wildcard Email Routing as
+a way to bypass that limit. Cloudflare separately documents
+[wildcard DNS and exact-record precedence](https://developers.cloudflare.com/dns/manage-dns-records/reference/wildcard-dns-records/).
+Working wildcard DNS alone does not establish Email Routing acceptance. If your
+account does not accept unlisted subdomains, use documented explicit onboarding
+within its limits, or the single-domain pattern. Do not assume that an existing
+Rebulk setup proves a fresh account's behavior.
+
+A fresh [public DNS observation](https://github.com/cole-robertson/cloudflare-email/blob/main/docs/verification/2026-09-13-wildcard-dns.json)
+also records Cloudflare MX answers for `test.rebulk.com` and two random subdomains
+without creating DNS records or adding those labels in Cloudflare. That report
+is public and deliberately marks `delivery_verified: false`; no email was sent
+by this DNS-only check.
+
+## 1. Fill in your setup worksheet
+
+Use a dedicated receiving namespace when the apex already serves Workspace or
+Microsoft 365. Example values:
+
+| Setting | Your example value |
+| --- | --- |
+| Cloudflare zone | `example.com` |
+| Receiving base | `in.example.com` |
+| Organization domain | `acme.in.example.com` |
+| Worker | `cloudflare-email-ingress` |
+| Rails ingress URL | `https://app.example.com/rails/action_mailbox/cloudflare/inbound_emails` |
+| Shared ingress secret | Generate with `openssl rand -hex 32`; save privately in Rails and the Worker |
+
+Keep staging and production Workers, buckets, queues, secrets, and receiving
+namespaces separate. The standalone deploy-button template takes one environment
+per copy; the regular CLI template uses `--env production` or another explicit env.
+
+## 2. Deploy the shared infrastructure
+
+[![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 Rails with gem 0.3+ first. The button copies the standalone Worker and
+prompts for `RAILS_INGRESS_URL` and `INGRESS_SECRET`. Its configuration includes
+private R2 storage, a Queue producer/consumer, once-per-minute recovery, and logs.
+Cloudflare documents [automatic R2/Queue provisioning and secret prompts](https://developers.cloudflare.com/workers/platform/deploy-buttons/).
+The button does not create email DNS, claim a domain, or register Rails mailboxes.
+
+## 3. Connect DNS and the Worker once
+
+For **one domain**, follow Cloudflare's documented
+[Email Routing onboarding](https://developers.cloudflare.com/email-service/get-started/route-emails/)
+and configure its [catch-all action](https://developers.cloudflare.com/email-service/configuration/email-routing-addresses/#catch-all-rule)
+as **Send to a Worker**, selecting your deployed Worker. This avoids one provider
+rule per local part. Review the actual zone/domain scope and any explicit rules
+that take precedence before saving.
+
+For a **Rebulk-style dynamic namespace**, first establish receiving on your account
+and retain the exact MX targets/priorities assigned by Cloudflare. Then, when
+reproducing and verifying wildcard receiving, the DNS template is:
+
+| DNS type | Name in zone `example.com` | Value |
+| --- | --- | --- |
+| MX | `*.in` | Each Cloudflare-assigned receiving MX target, with its assigned priority |
+
+Create one record per assigned target. Do not invent MX targets, point MX at a
+Worker URL, or replace the apex's existing MX records. Complete the service's
+other required DNS records through its onboarding instructions; do not blindly
+duplicate SPF records. Inspect the account's catch-all **Send to a Worker** rule
+and verify that it actually handles your intended namespace. A Cloudflare Worker
+HTTP route such as `*.example.com/*` is unrelated to email routing.
+
+An explicit DNS name can stop wildcard inheritance **even if its record is TXT
+or A rather than MX**. For example, an existing `acme.in.example.com` record may
+require its own receiving MX records. Test exact customer names as well as fresh
+ones. A wildcard also does not supply MX for the receiving base itself.
+
+## 4. Check without modifying infrastructure
+
+From either current Worker template, run:
+
+```sh
+npm run check:subdomains -- --base in.example.com --labels acme,globex
+```
+
+This requires only Node and DNS access, not a Cloudflare API key. It resolves MX
+for your chosen labels plus two fresh random labels. DNS lookups have bounded
+timeouts. JSON output distinguishes observed Cloudflare MX, other/missing MX, and
+lookup uncertainty. Exit zero means only that all queried names resolved to
+Cloudflare MX; `delivery_verified` remains false. Compare returned targets with
+your account's assigned targets. Existing explicit records can explain differences.
+The command ships in the repository templates; gem 0.3.0's already-published
+template predates it, so refresh your template copy to use it.
+
+For provider rule inspection, the gem also offers:
+
+```sh
+bin/rails cloudflare:email:check_route \
+  ADDRESS=invoices@acme.in.example.com \
+  WORKER_NAME=cloudflare-email-ingress \
+  ACCOUNT_ID=your-cloudflare-account-id
+```
+
+See [diagnostic credentials and limits](https://github.com/cole-robertson/cloudflare-email/blob/main/docs/routing-diagnostics.md).
+That diagnostic inspects exact-domain configured records; it does not resolve
+wildcard DNS inheritance. A working inherited-MX setup can therefore report
+missing exact records. Keep public DNS, provider rule inspection, and actual
+delivery evidence separate; do not force every organization through Cloudflare
+onboarding merely to make that diagnostic green.
+
+## 5. Prove the dynamic path before adopting it
+
+Use two new organization labels that have not been added individually in the
+Cloudflare dashboard:
+
+1. Check their public MX answers with the command above.
+2. Through trusted provisioning code, register both **exact** domains in Rails,
+   each against the correct stable organization key. Create a test mailbox for
+   each. Record your independently checked configuration evidence and activate
+   those test addresses so the gem can receive the verification messages.
+3. Send real email to both addresses from an external mailbox. Confirm the
+   Worker receives each, Rails retains the original message, and each appears
+   only in the correct organization's inbox. Record the message IDs and result.
+4. Repeat with a newly generated label without changing Cloudflare. If delivery
+   fails before the Worker, resolve the Cloudflare acceptance/onboarding issue;
+   changing Rails cannot fix a provider SMTP rejection.
+5. Rehearse Rails being unavailable, then verify retained R2 mail drains after
+   recovery without duplicate app records. Follow the
+   [durable recovery guide](https://github.com/cole-robertson/cloudflare-email/blob/main/templates/worker/docs/durable-inbound.md).
+
+These are deliberate test addresses; no real-email test is sent by the DNS checker.
+Successful tests establish evidence for your receiving namespace, not a guarantee
+that every future DNS change or provider policy will preserve it.
+
+## 6. Create organizations in Rails
+
+Once your namespace policy is verified, use the same gem APIs on organization
+creation. For example, from trusted app code after authorizing the organization:
+
+```ruby
+registry = Cloudflare::Email::Mailboxes
+organization_key = "organization-123" # Trusted stable app identity, not request input.
+domain = registry.register_domain(
+  domain: "acme.in.example.com",
+  tenant_key: organization_key,
+  account_id: Cloudflare::Email::Credentials.account_id
+)
+registry.activate_domain!(domain.id, evidence: verified_namespace_evidence)
+registry.for_tenant(organization_key) do |inboxes|
+  mailbox = inboxes.create(name: "Invoices", address: "invoices@acme.in.example.com",
+    owner_ref: "Organization:123")
+  inboxes.activate_address!(inboxes.addresses(mailbox.id).first.id,
+    evidence: verified_namespace_evidence)
+end
+```
+
+`verified_namespace_evidence` is your stored operator evidence from the setup and
+delivery checks, not a hard-coded claim of success. Make provisioning idempotent
+in your app, validate/reserve slugs, and resolve organization identity from trusted
+records. The gem stores exact domain registrations; it does not accept a `*`
+domain registration or silently authorize an arbitrary recipient from a web form.
+The management engine must obtain allowed domains from your host adapter. The
+hello-world starter intentionally stays single-domain; this recipe is the next
+step for an organization-aware app.
+
+A **Cloudflare routing catch-all** gets mail to the Worker. The gem's optional
+**mailbox catch-all** decides whether unknown local parts enter a mailbox. They
+are separate. Without the latter, unknown/suspended recipients return non-2xx and
+remain in durable pending storage until resolved. Monitor that backlog.
+
+Receiving on dynamic domains does not authorize sending from them. Cloudflare
+[Email Sending onboarding](https://developers.cloudflare.com/email-service/configuration/subdomains/#add-a-subdomain-to-email-sending)
+is separate; keep a verified shared sending domain unless you have explicitly
+onboarded the customer sending domain.