cloudflare-email 0.1.0 → 0.2.0

data/lib/cloudflare/email/mailboxes/models.rb

@@ -0,0 +1,148 @@
+require "active_record"
+require "cloudflare/email/active_record/base"
+
+module Cloudflare
+  module Email
+    module Mailboxes
+      # Domains are an administrator-maintained receiving directory. An active
+      # record is an assertion by the application, not DNS ownership verification.
+      class ReceivingDomain < Mailboxes.directory_base
+        self.table_name = "cloudflare_email_receiving_domains"
+        STATES = %w[pending active suspended].freeze
+        attr_readonly :domain, :tenant_key, :account_id
+        before_validation { self.domain = domain.to_s.strip.downcase }
+        validates :tenant_key, :account_id, presence: true
+        validates :domain, presence: true, uniqueness: true,
+          length: { maximum: 253 },
+          format: { with: /\A[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)+\z/ }
+        validates :state, inclusion: { in: STATES }
+        validate do
+          errors.add(:domain, "has an oversized label") if domain.to_s.split(".").any? { |label| label.length > 63 }
+        end
+        scope :active, -> { where(state: "active") }
+      end
+
+      module TenantIdentity
+        extend ActiveSupport::Concern
+        included do
+          attr_readonly :tenant_key
+          validates :tenant_key, presence: true
+          before_validation :assign_tenant_identity
+          validate :validate_tenant_identity
+          before_destroy :assert_tenant_identity!
+        end
+
+        private
+
+        def assign_tenant_identity
+          self.tenant_key ||= Tenancy.current_key
+        end
+
+        def validate_tenant_identity
+          return unless Tenancy.enabled? || Tenancy.current_key
+          Tenancy.require_context!
+          errors.add(:tenant_key, "does not match the current tenant") unless tenant_key == Tenancy.current_key
+        end
+
+        def assert_tenant_identity!
+          return unless Tenancy.enabled? || Tenancy.current_key
+          Tenancy.require_context!
+          raise ArgumentError, "record belongs to another tenant" unless tenant_key == Tenancy.current_key
+        end
+
+        def validate_parent_tenant(parent, attribute)
+          errors.add(attribute, "belongs to another tenant") if parent && parent.tenant_key != tenant_key
+        end
+      end
+
+      class Mailbox < Cloudflare::Email::ActiveRecord::Base
+        include TenantIdentity
+        self.table_name = "cloudflare_email_mailboxes"
+        has_many :addresses, class_name: "Cloudflare::Email::Mailboxes::Address", dependent: :restrict_with_exception
+        has_many :messages, class_name: "Cloudflare::Email::Mailboxes::Message", dependent: :restrict_with_exception
+        has_many :outbound_messages, class_name: "Cloudflare::Email::Mailboxes::OutboundMessage", dependent: :restrict_with_exception
+        validates :name, presence: true, length: { maximum: 255 }
+        validates :state, inclusion: { in: %w[active suspended] }
+        scope :active, -> { where(state: "active") }
+      end
+
+      class Address < Cloudflare::Email::ActiveRecord::Base
+        include TenantIdentity
+        self.table_name = "cloudflare_email_addresses"
+        belongs_to :mailbox, class_name: "Cloudflare::Email::Mailboxes::Mailbox"
+        attr_readonly :mailbox_id, :receiving_domain_id, :local_part, :domain, :address
+        before_validation :normalize_address
+        validates :mailbox, :receiving_domain_id, presence: true
+        validates :local_part, length: { in: 1..64 },
+          format: { with: /\A[a-z0-9!\#$%&'*+\/=\?^_`{|}~-]+(?:\.[a-z0-9!\#$%&'*+\/=\?^_`{|}~-]+)*\z/ }
+        validates :address, uniqueness: true, length: { maximum: 254 }
+        validates :state, inclusion: { in: %w[pending active suspended] }
+        validate :validate_directory
+        validate { validate_parent_tenant(mailbox, :mailbox) }
+        scope :active, -> { where(state: "active") }
+
+        def receiving_domain
+          ReceivingDomain.find_by(id: receiving_domain_id)
+        end
+
+        private
+
+        def normalize_address
+          self.local_part = local_part.to_s.strip.downcase
+          self.domain = domain.to_s.strip.downcase
+          self.address = "#{local_part}@#{domain}"
+        end
+
+        def validate_directory
+          registered = receiving_domain
+          unless registered && registered.domain == domain && registered.tenant_key == tenant_key
+            errors.add(:receiving_domain_id, "must match this tenant and domain")
+            return
+          end
+          if new_record? && registered.state != "active"
+            errors.add(:receiving_domain_id, "must be active before creating addresses")
+          end
+        end
+      end
+
+      class Message < Cloudflare::Email::ActiveRecord::Base
+        include TenantIdentity
+        self.table_name = "cloudflare_email_mailbox_messages"
+        belongs_to :mailbox, class_name: "Cloudflare::Email::Mailboxes::Mailbox"
+        attr_readonly :mailbox_id, :inbound_email_id, :recipient
+        validates :mailbox, :inbound_email_id, :recipient, presence: true
+        # The unique database index also supports create_or_find_by! retries.
+        validate { validate_parent_tenant(mailbox, :mailbox) }
+        scope :unread, -> { where(read_at: nil) }
+        scope :inbox, -> { where(archived_at: nil) }
+
+        def mark_read!
+          update!(read_at: Time.current)
+        end
+
+        def mark_unread!
+          update!(read_at: nil)
+        end
+
+        def archive!
+          update!(archived_at: Time.current)
+        end
+
+        def unarchive!
+          update!(archived_at: nil)
+        end
+      end
+
+      class OutboundMessage < Cloudflare::Email::ActiveRecord::Base
+        include TenantIdentity
+        self.table_name = "cloudflare_email_mailbox_outbound_messages"
+        belongs_to :mailbox, class_name: "Cloudflare::Email::Mailboxes::Mailbox"
+        belongs_to :outbound_delivery, class_name: "Cloudflare::Email::ActiveRecord::OutboundDelivery"
+        attr_readonly :mailbox_id, :outbound_delivery_id
+        validates :mailbox, :outbound_delivery, presence: true
+        # Enforce uniqueness in the database so idempotent link creation works.
+        validate { validate_parent_tenant(mailbox, :mailbox) }
+      end
+    end
+  end
+end

data/lib/cloudflare/email/mailboxes/provider_correlation.rb

@@ -0,0 +1,11 @@
+module Cloudflare
+  module Email
+    module Mailboxes
+      # Shared routing evidence, never inferred from a sender or event domain.
+      class ProviderCorrelation < Mailboxes.directory_base
+        self.table_name = "cloudflare_email_provider_correlations"
+        attr_readonly :account_id, :message_id, :recipient, :tenant_key, :outbound_delivery_id
+      end
+    end
+  end
+end

data/lib/cloudflare/email/mailboxes/service.rb

@@ -0,0 +1,288 @@
+require "digest"
+require "cloudflare/email/envelope"
+
+module Cloudflare
+  module Email
+    module Mailboxes
+      class << self
+        # Call after host authorization. The directory is a control-plane API,
+        # not a public endpoint accepting arbitrary customer domain claims.
+        def register_domain(domain:, tenant_key:, account_id:)
+          Tenancy.normalize_key(tenant_key)
+          ReceivingDomain.create!(domain: domain, tenant_key: tenant_key, account_id: account_id)
+        end
+
+        def activate_domain!(id, evidence:, sending_enabled: false)
+          raise ArgumentError, "verification evidence is required" if evidence.to_s.strip.empty?
+          domain = ReceivingDomain.find(id)
+          domain.update!(state: "active", provisioning_evidence: evidence,
+            verified_at: Time.now.utc, sending_enabled: sending_enabled)
+          domain
+        end
+
+        def for_tenant(key)
+          raise ArgumentError, "a block is required" unless block_given?
+          Tenancy.with(key) { yield Session.new(key) }
+        end
+
+        # Only call after verifying the complete ingress HMAC. Resolve before
+        # ActionMailbox or ActiveStorage accesses a tenant connection.
+        def receive(recipient:)
+          raise ArgumentError, "persistence block required" unless block_given?
+          address = canonical_address(recipient)
+          directory = ReceivingDomain.find_by(domain: address.split("@", 2).last, state: "active")
+          raise Unavailable, "receiving domain unavailable" unless directory
+          for_tenant(directory.tenant_key) do |session|
+            session.receive(address, directory) { yield }
+          end
+        rescue ::ActiveRecord::RecordNotFound
+          raise Unavailable, "mailbox address unavailable"
+        end
+
+        def canonical_address(value)
+          unless Envelope.valid_address?(value)
+            raise ValidationError, "mailbox address must be an ASCII dot-atom address"
+          end
+          value.downcase
+        end
+      end
+
+      class Session
+        attr_reader :tenant_key
+
+        def initialize(tenant_key)
+          @tenant_key = tenant_key
+        end
+
+        def mailboxes
+          context!
+          Mailbox.where(tenant_key: tenant_key)
+        end
+
+        def create(name:, address:, owner_ref: nil)
+          context!
+          Mailbox.transaction do
+            mailbox = Mailbox.create!(tenant_key: tenant_key, name: name, owner_ref: owner_ref)
+            add_address(mailbox.id, address: address)
+            mailbox
+          end
+        end
+
+        def add_address(mailbox_id, address:)
+          mailbox = active_mailbox!(mailbox_id)
+          canonical = Mailboxes.canonical_address(address)
+          local, domain = canonical.split("@", 2)
+          directory = ReceivingDomain.find_by!(domain: domain, tenant_key: tenant_key, state: "active")
+          Address.create!(tenant_key: tenant_key, mailbox_id: mailbox.id,
+            receiving_domain_id: directory.id, local_part: local, domain: domain,
+            address: canonical, state: "pending")
+        end
+
+        def activate_address!(address_id, evidence:)
+          context!
+          raise ArgumentError, "route verification evidence is required" if evidence.to_s.strip.empty?
+          address = Address.where(tenant_key: tenant_key).find(address_id)
+          active_mailbox!(address.mailbox_id)
+          active_domain!(address)
+          address.update!(state: "active", provisioning_evidence: evidence)
+          address
+        end
+
+        def provision_address!(address_id, provisioner:, worker_name:)
+          context!
+          raise ArgumentError, "provision outside a database transaction" if Address.connection.transaction_open?
+          address = Address.where(tenant_key: tenant_key).find(address_id)
+          active_mailbox!(address.mailbox_id)
+          active_domain!(address)
+          provisioner.provision(address: address.address, worker_name: worker_name)
+          # Failed requests leave the address pending; the existing provisioner
+          # upserts a rule, making a deliberate retry safe.
+          activate_address!(address.id, evidence: "Cloudflare address rule provisioned for Worker #{worker_name}")
+        end
+
+        def suspend(mailbox_id)
+          mailboxes.find(mailbox_id).tap { |mailbox| mailbox.update!(state: "suspended") }
+        end
+
+        def resume(mailbox_id)
+          mailboxes.find(mailbox_id).tap { |mailbox| mailbox.update!(state: "active") }
+        end
+
+        def messages(mailbox_id)
+          mailbox = mailboxes.find(mailbox_id)
+          Message.where(tenant_key: tenant_key, mailbox_id: mailbox.id)
+        end
+
+        def addresses(mailbox_id)
+          mailbox = mailboxes.find(mailbox_id)
+          Address.where(tenant_key: tenant_key, mailbox_id: mailbox.id)
+        end
+
+        def suspend_address(mailbox_id, address_id)
+          addresses(mailbox_id).find(address_id).tap { |address| address.update!(state: "suspended") }
+        end
+
+        def outbound_messages(mailbox_id)
+          mailbox = mailboxes.find(mailbox_id)
+          OutboundMessage.where(tenant_key: tenant_key, mailbox_id: mailbox.id)
+        end
+
+        def inbound_email(mailbox_id, message_id)
+          message = messages(mailbox_id).find(message_id)
+          ensure_storage_connection!
+          ::ActionMailbox::InboundEmail.find(message.inbound_email_id)
+        end
+
+        # Explicit permanent removal. Archive is the reversible default.
+        # Other mailbox memberships retain their shared raw source.
+        def purge_message(mailbox_id, message_id)
+          context!
+          ensure_storage_connection!
+          Message.transaction do
+            message = messages(mailbox_id).find(message_id)
+            inbound_id = message.inbound_email_id
+            message.destroy!
+            unless Message.where(inbound_email_id: inbound_id).exists?
+              ::ActionMailbox::InboundEmail.find_by(id: inbound_id)&.destroy!
+            end
+          end
+        end
+
+        def mark_read(mailbox_id, message_id, read: true)
+          messages(mailbox_id).find(message_id).update!(read_at: read ? Time.now.utc : nil)
+        end
+
+        def archive(mailbox_id, message_id, archived: true)
+          messages(mailbox_id).find(message_id).update!(archived_at: archived ? Time.now.utc : nil)
+        end
+
+        def prepare(mailbox_id, operation_key:, mail:)
+          context!
+          raise ArgumentError, "operation_key is required" unless operation_key.is_a?(String) && !operation_key.strip.empty?
+          mail = mail.message if mail.respond_to?(:message) && !mail.respond_to?(:encoded)
+          raise ValidationError, "mail must be a rendered Mail message" unless mail.respond_to?(:encoded)
+          mailbox = active_mailbox!(mailbox_id)
+          from = Array(mail.from)
+          raise ValidationError, "mail must have one mailbox From address" unless from.length == 1
+          sender = Array(mail.sender)
+          address = authorized_sender!(mailbox, from.first)
+          envelope_from = mail.respond_to?(:smtp_envelope_from) ? mail.smtp_envelope_from : from.first
+          unless Mailboxes.canonical_address(envelope_from) == address.address &&
+              sender.all? { |value| Mailboxes.canonical_address(value) == address.address }
+            raise ValidationError, "MIME and envelope sender must match the mailbox address"
+          end
+          domain = active_domain!(address)
+          raise Unavailable, "domain is not enabled for sending" unless domain.sending_enabled
+          key = "mailbox:#{Digest::SHA256.hexdigest(JSON.generate([tenant_key, mailbox.id, operation_key]))}"
+          Mailbox.transaction do
+            delivery = ActiveRecord::Outbox.prepare_mail(account_id: domain.account_id, operation_key: key, mail: mail)
+            OutboundMessage.create_or_find_by!(tenant_key: tenant_key, mailbox_id: mailbox.id,
+              outbound_delivery_id: delivery.id)
+            delivery
+          end
+        end
+
+        # Enqueue only after the outer transaction commits. No mail or model
+        # GlobalIDs are serialized into this job, just stable identities.
+        def enqueue(mailbox_id, operation_key:)
+          context!
+          raise ArgumentError, "enqueue after database commit" if Mailbox.connection.transaction_open?
+          linked_delivery!(mailbox_id, operation_key)
+          SendJob.perform_later(tenant_key, mailbox_id, operation_key)
+        end
+
+        def deliver(mailbox_id, operation_key:)
+          mailbox = active_mailbox!(mailbox_id)
+          delivery = linked_delivery!(mailbox.id, operation_key)
+          address = authorized_sender!(mailbox, delivery.from_address)
+          domain = active_domain!(address)
+          raise Unavailable, "domain is not enabled for sending" unless domain.sending_enabled && domain.account_id == delivery.account_id
+          ActiveRecord::Outbox.deliver(delivery, client: Mailboxes.client_for(tenant_key, delivery.account_id))
+          handler = Mailboxes.delivery_handler
+          delivery.with_lock { handler.call(delivery) } if handler.respond_to?(:call)
+          Events.register(delivery, tenant_key: tenant_key) if %w[accepted partial].include?(delivery.state) && delivery.provider_message_id
+          delivery
+        end
+
+        def reconcile(mailbox_id, operation_key:, **evidence, &handler)
+          delivery = linked_delivery!(mailbox_id, operation_key)
+          raise ArgumentError, "reconcile outside an outer transaction" if Mailbox.connection.transaction_open?
+          ActiveRecord::Outbox.reconcile(delivery, **evidence, &handler)
+          Events.register(delivery, tenant_key: tenant_key) if %w[accepted partial].include?(delivery.state) && delivery.provider_message_id
+          delivery
+        end
+
+        # A bounded repair pass after an enqueue gap or cross-database commit
+        # gap. Does not automatically resend sending/unknown/rejected rows.
+        def recover(limit: 100, after_id: 0)
+          context!
+          raise ArgumentError, "recover outside a database transaction" if Mailbox.connection.transaction_open?
+          raise ArgumentError, "limit must be 1..1000" unless limit.is_a?(Integer) && (1..1000).cover?(limit)
+          raise ArgumentError, "after_id must be nonnegative" unless after_id.is_a?(Integer) && after_id >= 0
+          links = OutboundMessage.where(tenant_key: tenant_key).where("id > ?", after_id).order(:id).limit(limit).to_a
+          links.each do |link|
+            delivery = ActiveRecord::OutboundDelivery.find(link.outbound_delivery_id)
+            if delivery.state == "prepared"
+              enqueue(link.mailbox_id, operation_key: delivery.operation_key) if mailboxes.find(link.mailbox_id).state == "active"
+            elsif %w[accepted partial].include?(delivery.state)
+              handler = Mailboxes.delivery_handler
+              delivery.with_lock { handler.call(delivery) } if handler.respond_to?(:call)
+              Events.register(delivery, tenant_key: tenant_key) if delivery.provider_message_id
+            end
+          end
+          links.last&.id
+        end
+
+        def receive(address, directory)
+          context!
+          ensure_storage_connection! if defined?(::ActionMailbox::InboundEmail)
+          Mailbox.transaction do
+            destination = Address.where(tenant_key: tenant_key, address: address, receiving_domain_id: directory.id, state: "active").first
+            raise Unavailable, "mailbox address unavailable" unless destination
+            mailbox = active_mailbox!(destination.mailbox_id)
+            active_domain!(destination)
+            inbound = yield
+            Message.create_or_find_by!(tenant_key: tenant_key, mailbox_id: mailbox.id,
+              inbound_email_id: inbound.id) { |row| row.recipient = address } if inbound
+            inbound
+          end
+        end
+
+        private
+
+        def context!
+          raise ConfigurationError, "mailbox session used outside its tenant context" unless Tenancy.require_context! == tenant_key
+        end
+
+        def ensure_storage_connection!
+          unless defined?(::ActionMailbox::InboundEmail) && ::ActionMailbox::InboundEmail.connection_pool == Mailbox.connection_pool &&
+              ::ActiveStorage::Blob.connection_pool == Mailbox.connection_pool
+            raise ConfigurationError, "ActionMailbox, ActiveStorage and mailbox records must share the tenant connection"
+          end
+        end
+
+        def active_mailbox!(id)
+          context!
+          mailboxes.where(state: "active").find(id)
+        end
+
+        def active_domain!(address)
+          ReceivingDomain.find_by!(id: address.receiving_domain_id, domain: address.domain,
+            tenant_key: tenant_key, state: "active")
+        end
+
+        def authorized_sender!(mailbox, address)
+          Address.where(tenant_key: tenant_key, mailbox_id: mailbox.id, state: "active")
+            .find_by!(address: Mailboxes.canonical_address(address))
+        end
+
+        def linked_delivery!(mailbox_id, operation_key)
+          mailbox = mailboxes.find(mailbox_id)
+          delivery = ActiveRecord::OutboundDelivery.find_by!(operation_key: operation_key)
+          OutboundMessage.find_by!(tenant_key: tenant_key, mailbox_id: mailbox.id, outbound_delivery_id: delivery.id)
+          delivery
+        end
+      end
+    end
+  end
+end

data/lib/cloudflare/email/mailboxes/shared_event_receipt.rb

@@ -0,0 +1,14 @@
+module Cloudflare
+  module Email
+    module Mailboxes
+      class SharedEventReceipt < Mailboxes.directory_base
+        self.table_name = "cloudflare_email_shared_event_receipts"
+        attr_readonly :account_id, :event_id, :message_id, :recipient, :payload_json
+
+        def event
+          DeliveryEvent.new(JSON.parse(payload_json))
+        end
+      end
+    end
+  end
+end

data/lib/cloudflare/email/mailboxes.rb

@@ -0,0 +1,11 @@
+# Explicit opt-in. Configure Tenancy and Mailboxes before loading this file.
+require "cloudflare-email"
+require "cloudflare/email/tenancy"
+require "cloudflare/email/mailboxes/configuration"
+require "cloudflare/email/active_record"
+require "cloudflare/email/mailboxes/models"
+require "cloudflare/email/mailboxes/events"
+require "cloudflare/email/mailboxes/service"
+require "cloudflare/email/mailboxes/jobs"
+
+Cloudflare::Email::Mailboxes.enable!

data/lib/cloudflare/email/message_id.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Cloudflare
+  module Email
+    # Correlation only: a Message-ID does not authorize access to a thread.
+    module MessageId
+      def self.normalize(value)
+        value.to_s.strip.sub(/\A<([^<>]+)>\z/, '\1')
+      end
+    end
+  end
+end

data/lib/cloudflare/email/provision_catchall_task.rb

@@ -6,7 +6,7 @@ module Cloudflare
   module Email
     # `bin/rails cloudflare:email:provision_catchall` — points a zone's
     # catch-all rule at the env-scoped ingress Worker. Useful for bounce
-    # handling, dev subdomains, and alias routing.
+    # handling and alias routing. Applies to the entire Cloudflare zone.
     class ProvisionCatchallTask < TaskBase
       def self.call(domain:, worker_name: nil, io: $stdout)
         new(io: io, domain: domain, worker_name: worker_name).call
@@ -16,11 +16,11 @@ module Cloudflare
 
       def run
         require_value!(management_token, "cloudflare.api_token or cloudflare.management_token")
-        require_value!(opts[:domain],    "DOMAIN=in.example.com")
+        require_value!(opts[:domain],    "DOMAIN=example.com (the Cloudflare zone name)")
 
         worker = opts[:worker_name] || Cloudflare::Email::WorkerDeployer.default_script_name
 
-        say "Provisioning catch-all:"
+        say "Provisioning zone-wide catch-all:"
         say "  Domain: #{opts[:domain]}"
         say "  Worker: #{worker}"
         say ""
@@ -29,7 +29,7 @@ module Cloudflare
         provisioner.provision_catch_all_for_domain(domain: opts[:domain], worker_name: worker)
 
         say "  ✓ Catch-all on #{opts[:domain]} now points at #{worker}."
-        say "  All unrouted addresses on this domain will hit your Worker."
+        say "  All unrouted addresses covered by this zone's catch-all will hit your Worker."
       end
     end
   end

data/lib/cloudflare/email/provision_route_task.rb

@@ -27,7 +27,8 @@ module Cloudflare
         provisioner = Cloudflare::Email::RoutingProvisioner.new(api_token: management_token)
         provisioner.provision(address: opts[:address], worker_name: worker)
 
-        say "  ✓ Route created/updated — mail to #{opts[:address]} will hit Worker #{worker}."
+        say "  ✓ Route created/updated for #{opts[:address]} → Worker #{worker}."
+        say "  Verify DNS propagation and send a test message to confirm delivery."
       end
     end
   end

data/lib/cloudflare/email/replay_events_job.rb

@@ -0,0 +1,18 @@
+require "active_job"
+require "cloudflare/email/active_record"
+
+module Cloudflare
+  module Email
+    class ReplayEventsJob < ::ActiveJob::Base
+      queue_as :mailers
+
+      def perform(account_id, message_id = nil)
+        handler = if defined?(Rails) && Rails.respond_to?(:application) && Rails.application
+          Rails.application.config.x.cloudflare_email.outbox_recipient_handler
+        end
+        ActiveRecord::DeliveryEvents.replay(account_id: account_id, message_id: message_id,
+          &(handler.method(:call) if handler.respond_to?(:call)))
+      end
+    end
+  end
+end

data/lib/cloudflare/email/response.rb

@@ -1,3 +1,5 @@
+require "cloudflare/email/message_id"
+
 module Cloudflare
   module Email
     class Response
@@ -9,18 +11,30 @@ module Cloudflare
       end
 
       def success?
-        return !!@raw["success"] if @raw.key?("success") && !@raw["success"].nil?
-        @status >= 200 && @status < 300
+        return false unless @status.is_a?(Integer) && @status >= 200 && @status < 300
+        return @raw["success"] == true if @raw.key?("success")
+        true
       end
 
       def result
         @raw["result"].is_a?(Hash) ? @raw["result"] : {}
       end
 
+      # Provider acceptance is not final delivery. A partial acceptance is true;
+      # inspect recipient outcomes before retrying any rejected recipients.
+      def accepted?
+        return false if %w[delivered queued permanent_bounces suppressed_recipients].any? { |key| result.key?(key) && !result[key].is_a?(Array) }
+        success? && (delivered.any? || queued.any? ||
+          (!message_id.to_s.strip.empty? && permanent_bounces.empty? && suppressed_recipients.empty?))
+      end
+
       def message_id
-        result["message_id"] ||
+        value = result["message_id"] ||
           dig_message_id(result["delivered"]) ||
           dig_message_id(result["queued"])
+        return nil unless value.is_a?(String)
+        normalized = MessageId.normalize(value)
+        value unless normalized.empty? || normalized.match?(/[\s<>[:cntrl:]]/)
       end
 
       def delivered
@@ -35,6 +49,10 @@ module Cloudflare
         Array(result["permanent_bounces"])
       end
 
+      def suppressed_recipients
+        Array(result["suppressed_recipients"])
+      end
+
       def errors
         Array(@raw["errors"])
       end