cloudflare-email 0.1.0 → 0.3.0

data/lib/cloudflare/email/client.rb

@@ -1,6 +1,10 @@
 require "net/http"
 require "json"
 require "uri"
+require "time"
+require "timeout"
+require "zlib"
+require "cloudflare/email/endpoint"
 
 module Cloudflare
   module Email
@@ -9,42 +13,67 @@ module Cloudflare
       DEFAULT_RETRIES  = 3
       DEFAULT_TIMEOUT  = 30
       DEFAULT_BACKOFF  = 0.5
+      DEFAULT_MAX_RESPONSE_BYTES = 1_048_576
       MAX_RETRY_AFTER  = 60 # seconds; never sleep longer than this even if server says so
 
       RETRYABLE_NETWORK = [
-        Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNRESET,
+        Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout, Errno::ECONNRESET,
         Errno::ECONNREFUSED, Errno::EHOSTUNREACH, EOFError, SocketError,
-        IOError
+        IOError, Timeout::Error, Net::HTTPBadResponse, Net::HTTPHeaderSyntaxError,
+        OpenSSL::SSL::SSLError, Zlib::Error
       ].freeze
+      PRE_SEND_NETWORK = [Net::OpenTimeout, Errno::ECONNREFUSED, Errno::EHOSTUNREACH, SocketError].freeze
 
-      attr_reader :account_id, :base_url, :retries, :timeout
+      attr_reader :account_id, :base_url, :retries, :timeout, :retry_ambiguous,
+                  :total_timeout, :max_response_bytes
 
       def initialize(account_id:, api_token:, base_url: DEFAULT_BASE_URL,
                      retries: DEFAULT_RETRIES, timeout: DEFAULT_TIMEOUT,
                      initial_backoff: DEFAULT_BACKOFF, max_retry_after: MAX_RETRY_AFTER,
-                     logger: nil)
-        raise ConfigurationError, "account_id is required" if account_id.nil? || account_id.to_s.empty?
-        raise ConfigurationError, "api_token is required"  if api_token.nil?  || api_token.to_s.empty?
+                     retry_ambiguous: false, logger: nil,
+                     total_timeout: timeout, max_response_bytes: DEFAULT_MAX_RESPONSE_BYTES)
+        unless account_id.is_a?(String) && account_id.match?(/\A[a-zA-Z0-9_-]+\z/)
+          raise ConfigurationError, "account_id is required and must be a single account identifier"
+        end
+        unless api_token.is_a?(String) && !api_token.empty? && !api_token.match?(/\s/)
+          raise ConfigurationError, "api_token is required and must not contain whitespace"
+        end
+        [[:timeout, timeout], [:total_timeout, total_timeout]].each do |name, value|
+          unless value.is_a?(Numeric) && value.real? && value.finite? && value.positive?
+            raise ConfigurationError, "#{name} must be a finite positive number"
+          end
+        end
+        unless max_response_bytes.is_a?(Integer) && max_response_bytes.positive?
+          raise ConfigurationError, "max_response_bytes must be a positive integer"
+        end
 
         @account_id      = account_id
         @api_token       = api_token
-        @base_url        = base_url
+        @base_url        = Endpoint.parse(base_url).to_s.delete_suffix("/")
         @retries         = retries
         @timeout         = timeout
+        @total_timeout   = total_timeout
+        @max_response_bytes = max_response_bytes
         @initial_backoff = initial_backoff
         @max_retry_after = max_retry_after
         @logger          = logger
+        @retry_ambiguous = retry_ambiguous
+      end
+
+      def inspect
+        "#<#{self.class.name} account_id=#{@account_id.inspect} api_token=[REDACTED]>"
       end
 
-      def send(from:, to:, subject:, text: nil, html: nil, cc: nil, bcc: nil,
+      def send(from:, subject:, to: nil, text: nil, html: nil, cc: nil, bcc: nil,
                reply_to: nil, headers: nil, attachments: nil)
         raise ValidationError, "must provide :text or :html" if text.nil? && html.nil?
+        raise ValidationError, "must provide a recipient in :to, :cc, or :bcc" if [to, cc, bcc].all? { |v| wrap(v).empty? }
 
         body = {
           from:    normalize_address(from),
-          to:      wrap(to).map  { |addr| normalize_address(addr) },
           subject: subject,
         }
+        body[:to]          = wrap(to).map { |addr| normalize_address(addr) } if to
         body[:text]        = text if text
         body[:html]        = html if html
         body[:cc]          = wrap(cc).map  { |a| normalize_address(a) } if cc
@@ -104,6 +133,10 @@ module Cloudflare
           response = request(:post, path, body)
           payload[:status]     = response.status
           payload[:message_id] = response.message_id
+          payload[:delivered] = response.delivered
+          payload[:queued] = response.queued
+          payload[:permanent_bounces] = response.permanent_bounces
+          payload[:suppressed_recipients] = response.suppressed_recipients
           response
         end
       end
@@ -125,7 +158,10 @@ module Cloudflare
           attempts += 1
           do_request(method, uri, body)
         rescue *RETRYABLE_NETWORK => e
-          raise NetworkError.new(e.message) if attempts > @retries
+          unless PRE_SEND_NETWORK.any? { |type| e.is_a?(type) } || @retry_ambiguous
+            raise NetworkError.new("provider response could not be read; delivery outcome is unknown; automatic retry disabled"), cause: nil
+          end
+          raise NetworkError.new("provider request could not be completed; request outcome is unknown"), cause: nil if attempts > @retries
           log_retry(attempts, e)
           sleep(backoff); backoff *= 2
           retry
@@ -135,7 +171,7 @@ module Cloudflare
           sleep(retry_after_from(e, backoff)); backoff *= 2
           retry
         rescue ServerError => e
-          raise if attempts > @retries
+          raise unless @retry_ambiguous && attempts <= @retries
           log_retry(attempts, e)
           sleep(backoff); backoff *= 2
           retry
@@ -145,7 +181,15 @@ module Cloudflare
       def retry_after_from(error, fallback_backoff)
         header = error.response.is_a?(Hash) ? error.response["retry_after"] : nil
         value  = header || fallback_backoff
-        seconds = value.to_f
+        seconds = if value.to_s.match?(/\A\d+(?:\.\d+)?\z/)
+          value.to_f
+        else
+          begin
+            Time.httpdate(value.to_s) - Time.now
+          rescue ArgumentError
+            fallback_backoff
+          end
+        end
         return fallback_backoff if seconds <= 0
         [seconds, @max_retry_after].min
       end
@@ -155,6 +199,8 @@ module Cloudflare
         http.use_ssl     = (uri.scheme == "https")
         http.open_timeout = @timeout
         http.read_timeout = @timeout
+        http.write_timeout = @timeout
+        http.max_retries = 0
 
         req_class = { post: Net::HTTP::Post, get: Net::HTTP::Get }.fetch(method)
         req = req_class.new(uri.request_uri)
@@ -164,13 +210,32 @@ module Cloudflare
         req["User-Agent"]    = "cloudflare-email-ruby/#{Cloudflare::Email::VERSION}"
         req.body = JSON.generate(body) if body
 
-        response = http.request(req)
-        handle_response(response)
+        raw = +"".b
+        response = nil
+        byte_limit = response_byte_limit(uri)
+        # Bound each network attempt, including trickling headers/body. Parsing,
+        # queue handlers, and database transactions are outside this deadline.
+        Timeout.timeout(@total_timeout) do
+          http.request(req) do |incoming|
+            response = incoming
+            incoming.read_body do |chunk|
+              # Net::HTTP yields decompressed bytes, so compressed expansion is
+              # subject to the same budget. Check before extending the buffer.
+              raise IOError, "provider response exceeds byte limit" if raw.bytesize + chunk.bytesize > byte_limit
+              raw << chunk
+            end
+          end
+        end
+        handle_response(response, raw)
+      end
+
+      def response_byte_limit(_uri)
+        @max_response_bytes
       end
 
-      def handle_response(response)
+      def handle_response(response, raw = response.body)
         status  = response.code.to_i
-        body    = parse_body(response.body)
+        body    = parse_body(raw)
         retry_after = response["Retry-After"]
 
         # Stash Retry-After on the error response so retry logic can use it.
@@ -178,6 +243,15 @@ module Cloudflare
 
         case status
         when 200..299
+          if body.is_a?(Hash) && body.key?("success") && body["success"] != true
+            raise Error.new(extract_message(body), status: status, response: body)
+          end
+          unless body.is_a?(Hash) && body["result"].is_a?(Hash)
+            raise Error.new("invalid successful API response; request outcome is unknown", status: status, response: body)
+          end
+          if body["errors"].is_a?(Array) && body["errors"].any?
+            raise Error.new(extract_message(body), status: status, response: body)
+          end
           Response.new(body, status: status)
         when 400, 422
           raise ValidationError.new(extract_message(body), status: status, response: body)
@@ -197,7 +271,7 @@ module Cloudflare
         return {} if raw.nil? || raw.empty?
         JSON.parse(raw)
       rescue JSON::ParserError
-        { "errors" => [{ "message" => raw.to_s[0, 200] }] }
+        { "errors" => [{ "message" => "invalid JSON API response; request outcome is unknown" }] }
       end
 
       def extract_message(body)
@@ -209,7 +283,8 @@ module Cloudflare
 
       def log_retry(attempt, error)
         return unless @logger
-        @logger.warn("[cloudflare-email] retry #{attempt}: #{error.class}: #{error.message}")
+        # Provider messages can echo message content or other sensitive data.
+        @logger.warn("[cloudflare-email] retry #{attempt}: #{error.class}")
       end
     end
   end

data/lib/cloudflare/email/consume_events_task.rb

@@ -0,0 +1,22 @@
+require "cloudflare/email/task_base"
+require "cloudflare/email/event_consumer"
+
+module Cloudflare
+  module Email
+    class ConsumeEventsTask < TaskBase
+      def run
+        handler = opts[:handler]
+        raise ConfigurationError, "configure config.x.cloudflare_email.event_handler with a callable" unless handler.respond_to?(:call)
+
+        consumer = EventConsumer.new(
+          account_id: account_id,
+          api_token: require_value!(credential(:queues_token), "cloudflare.queues_token / CLOUDFLARE_QUEUES_TOKEN"),
+          queue_id: require_value!(credential(:event_queue_id), "cloudflare.event_queue_id / CLOUDFLARE_EVENT_QUEUE_ID"),
+          domains: opts[:domains],
+        )
+        count = consumer.poll(batch_size: opts.fetch(:batch_size, 5), &handler.method(:call))
+        say "  Processed and acknowledged #{count} delivery event(s)."
+      end
+    end
+  end
+end

data/lib/cloudflare/email/delivery_event.rb

@@ -0,0 +1,70 @@
+require "json"
+require "time"
+
+module Cloudflare
+  module Email
+    # An outbound Email Sending event, delivered through Cloudflare Queues.
+    # Treat event_id as an idempotency key; events may arrive more than once
+    # or out of order. This is distinct from inbound ActionMailbox messages.
+    class DeliveryEvent
+      TYPES = %w[delivered deferred bounced failed rejected complained].freeze
+      attr_reader :raw
+
+      def initialize(raw)
+        @raw = raw
+        unless raw.is_a?(Hash) && raw["type"].is_a?(String) &&
+               raw["type"].match?(/\Acf\.email\.sending\.message\.[a-z][a-z0-9_]*\z/) &&
+               raw["payload"].is_a?(Hash) && raw["source"].is_a?(Hash) &&
+               raw["source"]["type"] == "email.sending" && raw["metadata"].is_a?(Hash) &&
+               raw["metadata"]["eventSchemaVersion"] == 1 &&
+               [event_id, message_id, account_id, domain, recipient].all? { |value| valid_identifier?(value) } &&
+               [true, false].include?(payload["terminal"]) &&
+               %w[delivery bounce complaint rejection failure].all? { |key| !payload.key?(key) || payload[key].is_a?(Hash) }
+          raise ValidationError, "invalid Email Sending event or unsupported schema version"
+        end
+        unless occurred_at.is_a?(String) && valid_identifier?(occurred_at)
+          raise ValidationError, "delivery event timestamp must be ISO8601"
+        end
+        Time.iso8601(occurred_at)
+      rescue ArgumentError
+        raise ValidationError, "delivery event timestamp must be ISO8601"
+      end
+
+      def type = raw["type"]
+      def status = type.delete_prefix("cf.email.sending.message.")
+      def known? = TYPES.include?(status)
+      def payload = raw["payload"]
+      def event_id = payload["eventId"]
+      def message_id = payload["messageId"]
+      def recipient = payload["recipient"]
+      def sender = payload["sender"]
+      def terminal? = payload["terminal"] == true
+      def domain = raw["source"]["domain"]
+      def account_id = raw["metadata"]["accountId"]
+      def occurred_at = raw["metadata"]["eventTimestamp"]
+      def delivery = payload["delivery"] || {}
+      def bounce = payload["bounce"] || {}
+      def complaint = payload["complaint"] || {}
+      def rejection = payload["rejection"] || {}
+      def failure = payload["failure"] || {}
+
+      # Use only after matching account, provider message ID, and recipient.
+      # Equal timestamps keep the existing state; unknown future types remain
+      # available in receipts but must not replace a recognized delivery state.
+      def supersedes?(occurred_at:, terminal:)
+        return false unless known?
+        return false if terminal && !terminal?
+
+        incoming = Time.iso8601(self.occurred_at.to_s)
+        previous = occurred_at.is_a?(Time) ? occurred_at : Time.iso8601(occurred_at.to_s) unless occurred_at.nil?
+        previous.nil? || incoming > previous
+      end
+
+      private
+
+      def valid_identifier?(value)
+        value.is_a?(String) && !value.strip.empty? && !value.match?(/[[:cntrl:]]/)
+      end
+    end
+  end
+end

data/lib/cloudflare/email/delivery_method.rb

@@ -25,6 +25,11 @@ module Cloudflare
           base_url:    settings[:base_url] || Cloudflare::Email::Client::DEFAULT_BASE_URL,
           retries:     settings.fetch(:retries,  Cloudflare::Email::Client::DEFAULT_RETRIES),
           timeout:     settings.fetch(:timeout,  Cloudflare::Email::Client::DEFAULT_TIMEOUT),
+          total_timeout: settings.fetch(:total_timeout, settings.fetch(:timeout, Cloudflare::Email::Client::DEFAULT_TIMEOUT)),
+          max_response_bytes: settings.fetch(:max_response_bytes, Cloudflare::Email::Client::DEFAULT_MAX_RESPONSE_BYTES),
+          initial_backoff: settings.fetch(:initial_backoff, Cloudflare::Email::Client::DEFAULT_BACKOFF),
+          max_retry_after: settings.fetch(:max_retry_after, Cloudflare::Email::Client::MAX_RETRY_AFTER),
+          retry_ambiguous: settings.fetch(:retry_ambiguous, false),
           logger:      settings[:logger],
         )
 

data/lib/cloudflare/email/deploy_worker_task.rb

@@ -6,8 +6,8 @@ module Cloudflare
     # `bin/rails cloudflare:email:deploy_worker` — uploads the Worker
     # script + both secrets via the Cloudflare API. No wrangler required.
     class DeployWorkerTask < TaskBase
-      def self.call(script_path: nil, ingress_url: nil, io: $stdout)
-        new(io: io, script_path: script_path, ingress_url: ingress_url).call
+      def self.call(script_path: nil, ingress_url: nil, delivery_mode: "durable", io: $stdout)
+        new(io: io, script_path: script_path, ingress_url: ingress_url, delivery_mode: delivery_mode).call
       end
 
       protected
@@ -20,12 +20,15 @@ module Cloudflare
         path = script_path
         raise "Worker script not found at #{path} — re-run `bin/rails g cloudflare:email:install`" unless File.exist?(path)
 
+        # Validate before uploading code or rotating any deployed secrets.
+        Endpoint.parse(url) unless url.to_s.empty?
+
         deployer = Cloudflare::Email::WorkerDeployer.new(
           account_id: account_id, api_token: management_token,
         )
 
         say "  Deploying Worker '#{deployer.script_name}'..."
-        deployer.deploy(script_path: path)
+        deployer.deploy(script_path: path, delivery_mode: opts[:delivery_mode])
         say "  ✓ Worker script deployed"
 
         deployer.put_secret("INGRESS_SECRET", ingress_secret)

data/lib/cloudflare/email/dev_ingress_guard.rb

@@ -0,0 +1,27 @@
+module Cloudflare
+  module Email
+    # cloudflared forces this origin Host. Restrict tunnel traffic before Rails
+    # routing, debug middleware and normal host authorization execute.
+    class DevIngressGuard
+      HOST = "cloudflare-email-ingress.localhost".freeze
+      PATH = "/rails/action_mailbox/cloudflare/inbound_emails".freeze
+      RESPONSE_HEADER = "x-cloudflare-email-ingress-only".freeze
+
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        return @app.call(env) unless env["HTTP_HOST"].to_s.downcase.split(":", 2).first == HOST
+        unless env["REQUEST_METHOD"] == "POST" && env["PATH_INFO"] == PATH
+          return [404, { "content-type" => "text/plain", "content-length" => "0", RESPONSE_HEADER => "1" }, []]
+        end
+        forwarded = env.dup
+        forwarded["HTTP_HOST"] = "localhost"
+        forwarded.delete("HTTP_X_FORWARDED_HOST")
+        forwarded.delete("HTTP_FORWARDED")
+        @app.call(forwarded)
+      end
+    end
+  end
+end

data/lib/cloudflare/email/dev_tunnel.rb

@@ -1,4 +1,6 @@
 require "cloudflare/email/worker_deployer"
+require "tempfile"
+require "cloudflare/email/dev_ingress_guard"
 
 module Cloudflare
   module Email
@@ -13,6 +15,7 @@ module Cloudflare
       end
 
       def initialize(port:, io: $stdout)
+        raise ArgumentError, "port must be between 1 and 65535" unless port.is_a?(Integer) && (1..65_535).cover?(port)
         @port       = port
         @io         = io
         @tunnel_pid = nil
@@ -51,22 +54,45 @@ module Cloudflare
       private
 
       def check_prerequisites
+        unless defined?(Rails) && Rails.respond_to?(:env) && Rails.env.development?
+          raise "cloudflare:email:dev only runs in development; use RAILS_ENV=development"
+        end
+        unless Rails.application.config.respond_to?(:action_mailbox) &&
+               Rails.application.config.action_mailbox.ingress == :cloudflare
+          raise "Set config.action_mailbox.ingress = :cloudflare in config/environments/development.rb"
+        end
+
         unless system("command -v cloudflared >/dev/null 2>&1")
           raise "cloudflared not found in PATH — install from https://developers.cloudflare.com/cloudflared/"
         end
         require "cloudflare/email/credentials"
-        if Cloudflare::Email::Credentials.account_id.empty? ||
-           Cloudflare::Email::Credentials.management_token.empty?
+        if Cloudflare::Email::Credentials.account_id.to_s.empty? ||
+           Cloudflare::Email::Credentials.management_token.to_s.empty?
           raise "Missing cloudflare.account_id or cloudflare.api_token in credentials " \
                 "(or CLOUDFLARE_ACCOUNT_ID / CLOUDFLARE_API_TOKEN env vars)"
         end
+        verify_ingress_guard!
+      end
+
+      def verify_ingress_guard!
+        http = Net::HTTP.new("127.0.0.1", @port, nil)
+        http.open_timeout = http.read_timeout = 2
+        request = Net::HTTP::Get.new("/")
+        request["Host"] = DevIngressGuard::HOST
+        response = http.request(request)
+        unless response.code == "404" && response[DevIngressGuard::RESPONSE_HEADER] == "1"
+          raise "Restart the development Rails server with the ingress-only middleware before opening a tunnel"
+        end
+      rescue SystemCallError, IOError, Timeout::Error
+        raise "Start the development Rails server with the ingress-only middleware before opening a tunnel"
       end
 
       def start_tunnel
         @io.puts "  Starting cloudflared tunnel on :#{@port}..."
-        @tunnel_log = File.open("/tmp/cloudflare-email-dev-tunnel.log", "w")
+        @tunnel_log = Tempfile.new(["cloudflare-email-dev-tunnel", ".log"])
         @tunnel_pid = spawn(
           "cloudflared", "tunnel", "--url", "http://127.0.0.1:#{@port}",
+          "--http-host-header", DevIngressGuard::HOST,
           out: @tunnel_log, err: @tunnel_log,
         )
       end
@@ -75,7 +101,7 @@ module Cloudflare
         deadline = Time.now + 30
         while Time.now < deadline
           sleep 0.5
-          log = File.read("/tmp/cloudflare-email-dev-tunnel.log") rescue ""
+          log = File.read(@tunnel_log.path) rescue ""
           if (match = log.match(%r{https://[a-z0-9\-]+\.trycloudflare\.com}))
             return match[0]
           end
@@ -89,7 +115,7 @@ module Cloudflare
           Process.wait(@tunnel_pid) rescue nil
           @tunnel_pid = nil
         end
-        @tunnel_log&.close
+        @tunnel_log&.close!
       end
 
     end

data/lib/cloudflare/email/doctor.rb

@@ -64,7 +64,7 @@ module Cloudflare
         if api_token.to_s.empty?
           record("credentials.cloudflare.api_token", FAIL, "missing — run bin/rails credentials:edit")
         else
-          record("credentials.cloudflare.api_token", OK, "#{api_token[0, 8]}...")
+          record("credentials.cloudflare.api_token", OK, "set (redacted)")
         end
       end
 
@@ -89,47 +89,20 @@ module Cloudflare
         if response[:ok]
           record("Account accessible", OK, response[:body].dig("result", "name") || account_id)
         elsif response[:status] == 403
-          # Narrowly-scoped send-only tokens don't have account read permission;
-          # that's a feature, not a bug. We already confirmed the token is valid.
-          record("Account accessible", OK, "send-scoped token (no account read — this is fine)")
+          # Send-scoped tokens may lack account read permission. A 403 cannot
+          # establish that this token can send for the configured account.
+          record("Account accessible", SKIP, "403 — account access unverified; token may lack account read permission")
         else
           record("Account accessible", FAIL, extract_error(response))
         end
       end
 
       def check_sending_domains
-        token      = credential(:api_token)
-        account_id = credential(:account_id)
-        return record("Sending domains", SKIP, "missing credentials") if token.to_s.empty? || account_id.to_s.empty?
-
-        response = request("GET", "/accounts/#{account_id}/email/sending/domains", token: token)
-        if response[:status] == 403 || response[:status] == 404
-          record("Sending domains", SKIP, "send-scoped token can't list domains (check the dashboard instead)")
-          return
-        end
-
-        unless response[:ok]
-          record("Sending domains", WARN, "could not list: #{extract_error(response)}")
-          return
-        end
-
-        domains = Array(response[:body]["result"])
-        if domains.empty?
-          record("Sending domains", WARN, "no sending domains set up — add one in the dashboard")
-          return
-        end
-
-        verified = domains.select { |d| d["verified"] == true || d["status"] == "verified" }
-        if verified.any?
-          names = verified.map { |d| d["name"] || d["domain"] }.compact.join(", ")
-          record("Sending domains", OK, "#{verified.size} verified (#{names})")
-        else
-          names = domains.map { |d| d["name"] || d["domain"] }.compact.join(", ")
-          record("Sending domains", WARN, "#{domains.size} configured but none verified (#{names})")
-        end
+        record("Sending domains", SKIP, "verify your sender domain in Email Sending in the Cloudflare dashboard")
       end
 
       def check_ingress_secret
+        return record("Ingress secret", SKIP, "Cloudflare inbound routing not selected") unless inbound_enabled?
         require "cloudflare/email/credentials"
         secret = Cloudflare::Email::Credentials.ingress_secret
 
@@ -143,6 +116,7 @@ module Cloudflare
       end
 
       def check_token_split
+        return record("Token split", SKIP, "send-only setup; management token optional") unless inbound_enabled?
         require "cloudflare/email/credentials"
         if Cloudflare::Email::Credentials.split_tokens?
           record("Token split", OK, "separate management_token set (good security posture)")
@@ -160,12 +134,16 @@ module Cloudflare
         when :cloudflare
           record("ActionMailbox ingress", OK, ":cloudflare")
         when nil
-          record("ActionMailbox ingress", WARN, "nil — inbound will 404. Set config.action_mailbox.ingress = :cloudflare")
+          record("ActionMailbox ingress", SKIP, "inbound routing not configured")
         else
-          record("ActionMailbox ingress", WARN, "#{ActionMailbox.ingress.inspect} — not :cloudflare, our controller will 404")
+          record("ActionMailbox ingress", SKIP, "#{ActionMailbox.ingress.inspect} — Cloudflare inbound routing not selected")
         end
       end
 
+      def inbound_enabled?
+        defined?(ActionMailbox) && ActionMailbox.respond_to?(:ingress) && ActionMailbox.ingress == :cloudflare
+      end
+
       def check_delivery_method_registered
         return record("Delivery method :cloudflare", SKIP, "ActionMailer not loaded") unless defined?(ActionMailer)
 
@@ -188,9 +166,9 @@ module Cloudflare
         warn_count = @results.count { |r| r[:status] == WARN }
 
         if fail_count.zero? && warn_count.zero?
-          @io.puts "  Everything looks good."
+          @io.puts "  Completed checks passed. Review skipped checks; live delivery is not verified."
         elsif fail_count.zero?
-          @io.puts "  #{warn_count} warning(s). Setup is usable but incomplete."
+          @io.puts "  #{warn_count} warning(s). Review warnings and skipped checks before relying on delivery."
         else
           @io.puts "  #{fail_count} failure(s), #{warn_count} warning(s). Fix failures before sending."
         end
@@ -228,7 +206,7 @@ module Cloudflare
 
         response = http.request(req)
         body = JSON.parse(response.body) rescue {}
-        { ok: response.code.to_i.between?(200, 299), status: response.code.to_i, body: body }
+        { ok: response.code.to_i.between?(200, 299) && body.is_a?(Hash) && body["success"] != false, status: response.code.to_i, body: body }
       rescue StandardError => e
         { ok: false, status: 0, body: { "errors" => [{ "message" => e.message }] } }
       end

data/lib/cloudflare/email/endpoint.rb

@@ -0,0 +1,24 @@
+require "uri"
+require "cloudflare/email/error"
+
+module Cloudflare
+  module Email
+    # Endpoints are trusted operator configuration, never message-derived URLs.
+    # Plain HTTP is only suitable for literal loopback development fixtures.
+    module Endpoint
+      LOOPBACK_HOSTS = %w[localhost 127.0.0.1 ::1].freeze
+
+      def self.parse(value, allow_loopback: true)
+        uri = URI.parse(value.to_s)
+        secure = uri.is_a?(URI::HTTPS)
+        local = allow_loopback && uri.is_a?(URI::HTTP) && LOOPBACK_HOSTS.include?(uri.hostname.to_s.downcase)
+        unless (secure || local) && !uri.hostname.to_s.empty? && !uri.userinfo && !uri.query && !uri.fragment
+          raise ConfigurationError, "endpoint must use HTTPS (HTTP only on literal loopback), without credentials, query or fragment"
+        end
+        uri
+      rescue URI::InvalidURIError
+        raise ConfigurationError, "endpoint must be a valid HTTPS URL"
+      end
+    end
+  end
+end

data/lib/cloudflare/email/engine.rb

@@ -1,4 +1,5 @@
 require "rails/engine"
+require "cloudflare/email/dev_ingress_guard"
 
 # Register the delivery method at engine load time (not inside an initializer)
 # so the `cloudflare_settings=` accessor exists before Rails' own
@@ -13,7 +14,39 @@ module Cloudflare
     class Engine < ::Rails::Engine
       isolate_namespace Cloudflare::Email
 
+      initializer "cloudflare-email.development_ingress_guard" do |app|
+        app.middleware.insert_before 0, DevIngressGuard if Rails.env.development?
+      end
+
+      config.to_prepare do
+        if (defined?(Cloudflare::Email::Tenancy) && Cloudflare::Email::Tenancy.enabled?) ||
+            (defined?(Cloudflare::Email::Mailboxes) && Cloudflare::Email::Mailboxes.enabled?)
+          require "cloudflare/email/tenant_job_context"
+          Cloudflare::Email::TenantJobContext.install_framework_jobs!
+        end
+        if defined?(Cloudflare::Email::Mailboxes) && Cloudflare::Email::Mailboxes.enabled? && defined?(::ActionMailbox::Engine)
+          require "cloudflare/email/mailboxes/inbound_retention"
+          ::ActionMailbox::InboundEmail.prepend(Cloudflare::Email::Mailboxes::InboundRetention) unless
+            ::ActionMailbox::InboundEmail.ancestors.include?(Cloudflare::Email::Mailboxes::InboundRetention)
+        end
+      end
+
+      config.before_initialize do
+        unless defined?(Cloudflare::Email::Management::Engine)
+          Rails.autoloaders.main.ignore(
+            File.expand_path("../../../app/controllers/cloudflare/email/management", __dir__),
+          )
+        end
+        unless defined?(::ActionMailbox::Engine)
+          Rails.autoloaders.main.ignore(
+            File.expand_path("../../../app/controllers/cloudflare/email/ingress_controller.rb", __dir__),
+          )
+        end
+      end
+
       initializer "cloudflare-email.routes" do |app|
+        next unless defined?(::ActionMailbox::Engine)
+
         app.routes.append do
           post "/rails/action_mailbox/cloudflare/inbound_emails",
                to: "cloudflare/email/ingress#create",