cloudflare-email 0.1.0 → 0.3.0

data/lib/cloudflare-email.rb

@@ -2,8 +2,11 @@ require "cloudflare/email/version"
 require "cloudflare/email/error"
 require "cloudflare/email/response"
 require "cloudflare/email/signing"
+require "cloudflare/email/envelope"
 require "cloudflare/email/credentials"
 require "cloudflare/email/client"
-require "cloudflare/email/secure_message_id"
+require "cloudflare/email/message_id"
+require "cloudflare/email/delivery_event"
+require "cloudflare/email/event_consumer"
 
 require "cloudflare/email/engine" if defined?(::Rails::Engine)

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

@@ -1,3 +1,4 @@
+require "rails/generators"
 require "rails/generators/base"
 require "securerandom"
 
@@ -16,7 +17,7 @@ module Cloudflare
                      desc: "Directory to copy the Cloudflare Worker template into"
 
         class_option :all_envs, type: :boolean, default: false,
-                     desc: "Also configure action_mailbox.ingress in development.rb and test.rb (not just production.rb)"
+                     desc: "Also configure action_mailbox.ingress in test.rb (development and production are configured by default)"
 
         class_option :deploy_worker, type: :boolean, default: nil,
                      desc: "Deploy the Worker via wrangler after setup (nil = interactive prompt)"
@@ -74,8 +75,8 @@ module Cloudflare
         def configure_action_mailbox_ingress
           return unless options[:inbound]
 
-          envs = ["production"]
-          envs += ["development", "test"] if options[:all_envs]
+          envs = ["development", "production"]
+          envs << "test" if options[:all_envs]
 
           envs.each do |env|
             file = "config/environments/#{env}.rb"
@@ -92,7 +93,7 @@ module Cloudflare
           return unless options[:inbound]
 
           worker_src = File.expand_path("../../../../templates/worker", __dir__)
-          directory worker_src, options[:worker_dir]
+          directory worker_src, options[:worker_dir], exclude_pattern: %r{/(node_modules|\.wrangler|\.dev\.vars(?:\.[^/]*)?|\.env(?:\.[^/]*)?)(/|$)}
         end
 
         def maybe_deploy_worker
@@ -101,37 +102,45 @@ 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 "  Run `bin/rails cloudflare:email:deploy_worker URL=https://yourapp.com#{ingress_path}`"
+            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 ""
             say "  Alternatively, deploy now via wrangler if it's installed locally." if wrangler_installed?
           end
 
-          if should_deploy && wrangler_installed?
+          if should_deploy
+            raise Thor::Error, "Install wrangler or use the cloudflare:email:deploy_worker Rails task" unless wrangler_installed?
             wrangler_deploy
           end
         end
 
-        def wrangler_deploy
-          @ingress_secret = SecureRandom.hex(32)
+        no_tasks do
+          def wrangler_deploy
+            @ingress_secret = SecureRandom.hex(32)
 
-          inside options[:worker_dir] do
-            run "npm install --legacy-peer-deps", abort_on_failure: true
+            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})")
-            if ingress_url.to_s.strip.empty?
-              say "  Skipping Worker deploy — no URL supplied. Re-run `wrangler deploy` manually when ready.", :yellow
-              return
+              ingress_url = ask("Rails ingress URL? (e.g. https://yourapp.com#{ingress_path})")
+              if ingress_url.to_s.strip.empty?
+                say "  Skipping Worker deploy — no URL supplied. Re-run `npm run deploy -- --env production` manually when ready.", :yellow
+                return
+              end
+
+              require "cloudflare/email/endpoint"
+              Cloudflare::Email::Endpoint.parse(ingress_url.strip)
+
+              run "npm run deploy -- --env production", abort_on_failure: true
+              run_with_stdin("npx --no-install wrangler secret put RAILS_INGRESS_URL --env production", ingress_url.strip)
+              run_with_stdin("npx --no-install wrangler secret put INGRESS_SECRET --env production", @ingress_secret)
             end
 
-            run_with_stdin("wrangler secret put RAILS_INGRESS_URL", ingress_url.strip)
-            run_with_stdin("wrangler secret put INGRESS_SECRET",    @ingress_secret)
-            run "wrangler deploy", abort_on_failure: false
+            @worker_deployed = true
           end
-
-          @worker_deployed = true
+          private :wrangler_deploy
         end
 
         def print_post_install
@@ -155,41 +164,43 @@ module Cloudflare
           say "       bin/rails cloudflare:email:doctor"
           say ""
           say "  3. Send a test email:"
-          say "       TO=you@example.com bin/rails cloudflare:email:send_test"
+          say "       FROM=hello@your-verified-domain.com TO=you@example.com bin/rails cloudflare:email:send_test"
           say ""
 
           if options[:inbound] && !@worker_deployed
             say "  4. Deploy the Worker (pick one):"
-            say "       # Pure Ruby (recommended — no wrangler/Node required):"
-            say "       bin/rails cloudflare:email:deploy_worker URL=https://yourapp.com#{ingress_path}"
+            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 install --legacy-peer-deps"
-            say "       wrangler secret put INGRESS_SECRET     # paste #{@ingress_secret[0, 8]}..."
-            say "       wrangler secret put RAILS_INGRESS_URL  # https://yourapp.com#{ingress_path}"
-            say "       wrangler deploy"
+            say "       npm ci"
+            say "       npm run deploy -- --env production"
+            say "       npx --no-install wrangler secret put INGRESS_SECRET --env production # paste #{@ingress_secret[0, 8]}..."
+            say "       npx --no-install wrangler secret put RAILS_INGRESS_URL --env production # https://yourapp.com#{ingress_path}"
             say ""
           end
 
           if options[:inbound]
             say "  5. For local dev (tunnels cloudflared to your Worker):"
-            say "       bin/rails cloudflare:email:dev"
+            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 ""
             say "  6. In the Cloudflare dashboard:"
             say "       Email Routing -> Routes -> Send to a Worker -> #{worker_name}"
             say ""
             say "  Dashboard deep-links:"
             say "    API tokens:       https://dash.cloudflare.com/profile/api-tokens"
-            say "    Sending domains:  https://dash.cloudflare.com/?to=/:account/email/sending"
-            say "    Email routing:    https://dash.cloudflare.com/?to=/:account/email/routing"
+            say "    Sending domains:  https://dash.cloudflare.com/?to=/:account/email-service/sending"
+            say "    Email routing:    https://dash.cloudflare.com/?to=/:account/email-service/routing"
             say ""
             say "  Rotation: to rotate the ingress secret, update cloudflare.ingress_secret"
-            say "  in Rails credentials AND re-run `wrangler secret put INGRESS_SECRET` in"
+            say "  in Rails credentials AND re-run `wrangler secret put INGRESS_SECRET --env production` in"
             say "  #{options[:worker_dir]}/ with the new value, then redeploy the Worker."
             say ""
-            say "  Dev/test: by default only production.rb is wired to :cloudflare ingress."
-            say "  Re-run with --all-envs to also configure development.rb and test.rb."
+            say "  Development and production are wired to :cloudflare ingress."
+            say "  Re-run with --all-envs to also configure test.rb."
           end
           say ""
         end
@@ -211,14 +222,19 @@ module Cloudflare
         end
 
         def worker_name
-          "cloudflare-email-ingress"
+          "cloudflare-email-ingress-production"
+        end
+
+        def worker_script_argument
+          require "shellwords"
+          Shellwords.escape(File.join(options[:worker_dir], "src/index.js"))
         end
 
         def run_with_stdin(cmd, input)
           require "open3"
           out, err, status = Open3.capture3(cmd, stdin_data: input + "\n")
           unless status.success?
-            say "  #{cmd} failed: #{err.empty? ? out : err}", :red
+            raise Thor::Error, "#{cmd} failed: #{err.empty? ? out : err}"
           end
         end
       end

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/mailboxes_generator.rb

@@ -0,0 +1,55 @@
+require "rails/generators"
+require "rails/generators/active_record"
+require "generators/cloudflare/email/outbox/outbox_generator"
+require "generators/cloudflare/email/tracking/tracking_generator"
+
+module Cloudflare
+  module Email
+    module Generators
+      class MailboxesGenerator < ::Rails::Generators::Base
+        include ::ActiveRecord::Generators::Migration
+        namespace "cloudflare:email:mailboxes"
+        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"
+        class_option :directory_migrations_path, type: :string, default: "db/migrate",
+          desc: "Migration directory applied only to the shared directory database"
+
+        def copy_migrations
+          invoke "cloudflare:email:outbox", [], migrations_path: options[:tenant_migrations_path]
+          invoke "cloudflare:email:tracking", [], migrations_path: options[:tenant_migrations_path]
+          migration_template "create_cloudflare_email_receiving_domains.rb",
+            File.join(options[:directory_migrations_path], "create_cloudflare_email_receiving_domains.rb")
+          migration_template "create_cloudflare_email_shared_events.rb",
+            File.join(options[:directory_migrations_path], "create_cloudflare_email_shared_events.rb")
+          migration_template "create_cloudflare_email_mailboxes.rb",
+            File.join(options[:tenant_migrations_path], "create_cloudflare_email_mailboxes.rb")
+        end
+
+        def create_initializer
+          create_file "config/initializers/00_cloudflare_email_tenancy.rb", <<~RUBY
+            # Single database: no configuration is necessary.
+            # Separate tenant databases: configure BEFORE the optional models load.
+            # Replace these application-specific adapter names with your own:
+            # require "cloudflare/email/tenancy"
+            # Cloudflare::Email::Tenancy.configure(
+            #   base_class: TenantRecord,
+            #   switch: ->(key, &block) { TenantRecord.with_tenant(key, &block) },
+            #   current: -> { TenantRecord.current_tenant }
+            # )
+            # require "cloudflare/email/mailboxes/configuration"
+            # Cloudflare::Email::Mailboxes.configure(directory_base: SharedRecord)
+            # ActionMailbox and ActiveStorage must use this same tenant connection.
+            # See docs/mailboxes.md for the complete application setup.
+          RUBY
+          create_file "config/initializers/cloudflare_email_mailboxes.rb", <<~RUBY
+            # Optional mailbox persistence. Run the generated migrations first.
+            # For database tenancy, configure Tenancy and the shared directory
+            # base before requiring cloudflare/email/mailboxes. See docs/mailboxes.md.
+            require "cloudflare/email/mailboxes"
+          RUBY
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+class CreateCloudflareEmailMailboxes < ActiveRecord::Migration[7.1]
+  def up
+    create_table :cloudflare_email_mailboxes do |t|
+      t.string :tenant_key, null: false
+      t.string :name, null: false
+      t.string :owner_ref
+      t.string :state, null: false, default: "active"
+      t.timestamps
+    end
+    add_index :cloudflare_email_mailboxes, [:tenant_key, :owner_ref], name: "idx_cf_email_mailbox_owner"
+
+    create_table :cloudflare_email_addresses do |t|
+      t.string :tenant_key, null: false
+      t.references :mailbox, null: false, index: false, foreign_key: { to_table: :cloudflare_email_mailboxes }
+      # The domain directory can live in another database: no cross-database FK.
+      t.bigint :receiving_domain_id, null: false
+      t.string :local_part, null: false
+      t.string :domain, null: false
+      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
+      t.references :mailbox, null: false, index: false, foreign_key: { to_table: :cloudflare_email_mailboxes }
+      # No database FK to the optional Rails table; the ingress service requires
+      # the same connection and manages membership+raw source atomically.
+      t.bigint :inbound_email_id, null: false
+      t.string :recipient, null: false
+      t.datetime :read_at
+      t.datetime :archived_at
+      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, [:tenant_key, :mailbox_id, :archived_at, :id], name: "idx_cf_email_mailbox_inbox"
+
+    create_table :cloudflare_email_mailbox_outbound_messages do |t|
+      t.string :tenant_key, null: false
+      t.references :mailbox, null: false, index: false, foreign_key: { to_table: :cloudflare_email_mailboxes }
+      t.references :outbound_delivery, null: false, index: false, foreign_key: { to_table: :cloudflare_email_outbound_deliveries }
+      t.timestamps
+    end
+    add_index :cloudflare_email_mailbox_outbound_messages, :outbound_delivery_id, unique: true, name: "idx_cf_email_mailbox_outbound"
+    add_index :cloudflare_email_mailbox_outbound_messages, :mailbox_id, name: "idx_cf_email_outbound_mailbox"
+  end
+
+  def down
+    raise ActiveRecord::IrreversibleMigration, "Preserve mailbox ownership and retained messages; use a forward fix"
+  end
+end

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

@@ -0,0 +1,16 @@
+class CreateCloudflareEmailReceivingDomains < ActiveRecord::Migration[7.1]
+  def change
+    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 :state, null: false, default: "pending"
+      t.boolean :sending_enabled, null: false, default: false
+      t.text :provisioning_evidence
+      t.datetime :verified_at
+      t.timestamps
+    end
+    add_index :cloudflare_email_receiving_domains, :domain, unique: true, name: "idx_cf_email_directory_domain"
+    add_index :cloudflare_email_receiving_domains, [:tenant_key, :state], name: "idx_cf_email_directory_tenant"
+  end
+end

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

@@ -0,0 +1,35 @@
+class CreateCloudflareEmailSharedEvents < ActiveRecord::Migration[7.2]
+  def up
+    create_table :cloudflare_email_shared_event_receipts do |t|
+      t.string :account_id, null: false
+      t.string :event_id, null: false
+      t.string :message_id, null: false
+      t.string :recipient, null: false
+      t.text :payload_json, null: false
+      t.string :state, null: false, default: "pending"
+      t.datetime :applied_at
+      t.timestamps
+    end
+    add_index :cloudflare_email_shared_event_receipts, [:account_id, :event_id], unique: true,
+      name: "idx_cf_shared_events_identity"
+    add_index :cloudflare_email_shared_event_receipts, [:state, :id], name: "idx_cf_shared_events_replay"
+
+    create_table :cloudflare_email_provider_correlations do |t|
+      t.string :account_id, null: false
+      t.string :message_id, null: false
+      t.string :recipient, null: false
+      t.string :tenant_key, null: false
+      t.bigint :outbound_delivery_id, null: false
+      t.timestamps
+    end
+    add_index :cloudflare_email_provider_correlations,
+      [:account_id, :message_id, :recipient, :tenant_key, :outbound_delivery_id], unique: true,
+      name: "idx_cf_provider_correlations_identity"
+    add_index :cloudflare_email_provider_correlations, [:account_id, :message_id, :recipient],
+      name: "idx_cf_provider_correlations_lookup"
+  end
+
+  def down
+    raise ActiveRecord::IrreversibleMigration, "Preserve tenant routing and event deduplication evidence; use a forward fix"
+  end
+end

data/lib/generators/cloudflare/email/outbox/outbox_generator.rb

@@ -0,0 +1,28 @@
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Cloudflare
+  module Email
+    module Generators
+      class OutboxGenerator < ::Rails::Generators::Base
+        include ::ActiveRecord::Generators::Migration
+        namespace "cloudflare:email:outbox"
+        source_root File.expand_path("templates", __dir__)
+        class_option :migrations_path, type: :string, default: "db/migrate"
+
+        def copy_outbox_migration
+          migration_template "create_cloudflare_email_outbox.rb", File.join(options[:migrations_path], "create_cloudflare_email_outbox.rb")
+        end
+
+        def create_initializer
+          create_file "config/initializers/cloudflare_email_outbox.rb", <<~RUBY
+            # Opt in after running db:migrate. Never perform network delivery inside a database transaction.
+            require "cloudflare/email/active_record"
+            require "cloudflare/email/send_job"
+            require "cloudflare/email/replay_events_job"
+          RUBY
+        end
+      end
+    end
+  end
+end

data/lib/generators/cloudflare/email/outbox/templates/create_cloudflare_email_outbox.rb

@@ -0,0 +1,48 @@
+class CreateCloudflareEmailOutbox < ActiveRecord::Migration[7.1]
+  def up
+    create_table :cloudflare_email_outbound_deliveries do |t|
+      t.string :account_id, null: false
+      t.string :operation_key, null: false
+      t.string :from_address, null: false
+      t.text :recipients_json, null: false
+      t.binary :mime_message, null: false
+      t.string :snapshot_digest, null: false
+      t.string :state, null: false, default: "prepared"
+      t.string :provider_message_id
+      t.text :response_json
+      t.string :error_class
+      t.datetime :request_started_at
+      t.datetime :completed_at
+      t.timestamps
+    end
+    add_index :cloudflare_email_outbound_deliveries, [:account_id, :operation_key], unique: true, name: "idx_cf_email_outbound_operation"
+    add_index :cloudflare_email_outbound_deliveries, [:account_id, :provider_message_id], name: "idx_cf_email_outbound_provider"
+    add_index :cloudflare_email_outbound_deliveries, [:state, :id], name: "idx_cf_email_outbound_pending"
+
+    create_table :cloudflare_email_outbound_recipients do |t|
+      t.references :outbound_delivery, null: false, index: false, foreign_key: { to_table: :cloudflare_email_outbound_deliveries }
+      t.string :recipient, null: false
+      t.string :state, null: false, default: "prepared"
+      t.string :acceptance_state, null: false, default: "prepared"
+      t.datetime :occurred_at
+      t.boolean :terminal, null: false, default: false
+      t.timestamps
+    end
+    add_index :cloudflare_email_outbound_recipients, [:outbound_delivery_id, :recipient], unique: true, name: "idx_cf_email_outbound_recipient"
+
+    create_table :cloudflare_email_outbound_reconciliations do |t|
+      t.references :outbound_delivery, null: false, index: { name: "idx_cf_email_reconciliation_delivery" }, foreign_key: { to_table: :cloudflare_email_outbound_deliveries }
+      t.string :actor, null: false
+      t.text :reason, null: false
+      t.text :evidence, null: false
+      t.string :outcome, null: false
+      t.string :provider_message_id
+      t.text :recipients_json
+      t.timestamps
+    end
+  end
+
+  def down
+    raise ActiveRecord::IrreversibleMigration, "Preserve delivery evidence; use a forward fix or a reconciled backup"
+  end
+end

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/generators/cloudflare/email/templates/initializer.rb

@@ -8,13 +8,13 @@
 # Inbound: ActionMailbox ingress is mounted at
 #   /rails/action_mailbox/cloudflare/inbound_emails
 # Set `config.action_mailbox.ingress = :cloudflare` (the install generator
-# does this for production by default) and configure cloudflare.ingress_secret
+# does this for development and production by default) and configure cloudflare.ingress_secret
 # in your Rails credentials.
 
 Rails.application.configure do
   config.action_mailer.delivery_method = :cloudflare
   config.action_mailer.cloudflare_settings = {
-    account_id: Rails.application.credentials.dig(:cloudflare, :account_id),
-    api_token:  Rails.application.credentials.dig(:cloudflare, :api_token),
+    account_id: Cloudflare::Email::Credentials.account_id,
+    api_token:  Cloudflare::Email::Credentials.api_token,
   }
 end

data/lib/generators/cloudflare/email/templates/main_mailbox.rb

@@ -6,13 +6,8 @@
 # ActionMailbox API (mail is a Mail::Message, inbound_email is the AR record).
 class MainMailbox < ApplicationMailbox
   def process
-    Rails.logger.info(
-      "[cloudflare-email] inbound received: " \
-      "from=#{mail.from&.first.inspect} " \
-      "to=#{Array(mail.to).inspect} " \
-      "subject=#{mail.subject.inspect} " \
-      "message_id=#{mail.message_id.inspect}"
-    )
+    # Keep message content and personal addresses out of application logs.
+    Rails.logger.info("[cloudflare-email] inbound received: inbound_email_id=#{inbound_email.id}")
 
     # Example ways to pull content out of the incoming message:
     #

data/lib/generators/cloudflare/email/tracking/templates/create_cloudflare_email_event_receipts.rb

@@ -0,0 +1,22 @@
+class CreateCloudflareEmailEventReceipts < ActiveRecord::Migration[7.1]
+  def up
+    create_table :cloudflare_email_event_receipts do |t|
+      t.string :account_id, null: false
+      t.string :event_id, null: false
+      t.string :message_id, null: false
+      t.text :payload_json, null: false
+      t.string :state, null: false, default: "pending"
+      t.datetime :applied_at
+      t.timestamps
+    end
+    add_index :cloudflare_email_event_receipts, [:account_id, :event_id], unique: true,
+      name: "idx_cf_email_receipts_account_event"
+    add_index :cloudflare_email_event_receipts, [:account_id, :message_id],
+      name: "idx_cf_email_receipts_account_message"
+    add_index :cloudflare_email_event_receipts, [:state, :id], name: "idx_cf_email_receipts_replay"
+  end
+
+  def down
+    raise ActiveRecord::IrreversibleMigration, "Preserve event deduplication evidence; use a forward fix or a reconciled backup"
+  end
+end

data/lib/generators/cloudflare/email/tracking/tracking_generator.rb

@@ -0,0 +1,26 @@
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Cloudflare
+  module Email
+    module Generators
+      class TrackingGenerator < ::Rails::Generators::Base
+        include ::ActiveRecord::Generators::Migration
+        namespace "cloudflare:email: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_event_receipts.rb", File.join(options[:migrations_path], "create_cloudflare_email_event_receipts.rb")
+        end
+
+        def create_initializer
+          create_file "config/initializers/cloudflare_email_tracking.rb", <<~RUBY
+            # Opt in to durable delivery-event receipts after running db:migrate.
+            require "cloudflare/email/active_record/event_inbox"
+          RUBY
+        end
+      end
+    end
+  end
+end