mailbox-kit 0.1.0

data/docs/integration.md

@@ -0,0 +1,283 @@
+# Integration guide
+
+Persistent inboxes on top of Action Mailbox, independent of your email provider. Rails
+already stores and parses email, routes it to processing handlers, and provides
+configurable retention. Mailbox Kit adds inbox identities, addresses/aliases,
+membership, read/archive state, scoped access and a server-rendered management UI.
+SQLite works; separate tenant databases are opt-in.
+
+This package is maintained alongside `cloudflare-email` so changes to the core and
+its first integration can be tested together. It is not yet published. In this
+checkout use `gem "mailbox-kit", path: "mailbox-kit"`. Once released, applications
+can use `gem "mailbox-kit", "~> 0.1"`.
+
+## What belongs where?
+
+| Layer | Responsibility |
+| --- | --- |
+| Mailbox Kit | Inbox identities, addresses, recipient lookup, membership, read/archive/purge, selective retention, tenant context, management UI |
+| Rails | InboundEmail records, original MIME/ActiveStorage, parsing, processing callbacks/status, routing jobs, configurable retention, and ActionMailer |
+| Provider integration | Verify incoming requests and envelope recipients, deliver outgoing messages, authenticate delivery feedback, configure DNS/routes |
+| Your application | Users, organizations, sites, permissions, sender acceptance and business workflows |
+
+Mailbox Kit does not require Cloudflare, configure DNS, or send messages by itself.
+`cloudflare-email` supplies its existing Worker ingress, sending/outbox, feedback,
+and provisioning integration. Other providers can call the core receiving APIs;
+this release does not claim complete SES, Postmark, or generic outbound adapters.
+The tests exercise Rails' stock Postmark HTTP ingress followed by explicit kit
+attachment in one database; provider setup, dynamic envelope authorization and
+provider outage behavior are separate integration responsibilities.
+Inbound and outbound need not use the same service. A mailbox has no `provider`
+attribute: receiving through one provider does not authorize sending through it.
+
+## Create an inbox
+
+Use Rails 7.2–8.1 with Active Record. Install ActionMailbox when you want its raw
+message storage and the message-reading UI:
+
+```sh
+bin/rails action_mailbox:install
+bin/rails generate mailbox_kit:install
+bin/rails db:migrate
+```
+
+The generator adds an initializer requiring `mailbox_kit/mailboxes`. Register a
+domain from trusted setup code after configuring your receiving provider:
+
+```ruby
+boxes = MailboxKit::Mailboxes
+domain = boxes.register_domain(domain: "in.example.com", tenant_key: "workspace")
+boxes.activate_domain!(domain.id, evidence: "Receiving route verified by an end-to-end test")
+
+boxes.for_tenant("workspace") do |session|
+  inbox = session.create(
+    name: "Support", address: "support@in.example.com", owner_ref: "team:stable-uuid"
+  )
+  session.activate_address!(inbox.addresses.first.id, evidence: "Provider route verified")
+  # Aliases belong to the same inbox; each starts pending until activated.
+  session.add_address(inbox.id, address: "help@in.example.com")
+end
+```
+
+`workspace` is an explicit scope in a single database; it does not turn on database
+tenancy. Domain/address activation records evidence supplied by your trusted
+application. It does not verify DNS or grant permission to send from that address.
+
+`owner_ref` is currently an application-managed reference, not a foreign key or an
+authorization grant. Use stable identities, rather than reusable numeric IDs.
+Automatic `has_mailbox` owner bindings and deletion reconciliation are a separate
+follow-up; this extraction does not introduce a callback that could silently
+reassign an old address to a new owner.
+
+## Reuse Action Mailbox
+
+For a receive-and-process application, Action Mailbox alone may be enough. It
+already supports dynamic handlers through regex/callable routes, processing
+callbacks, test helpers, and the development conductor at
+`/rails/conductor/action_mailbox/inbound_emails`. The kit does not replace those.
+Rails' `delivered` status means an inbound handler finished processing; read and
+archive state belong to the kit's inbox membership instead.
+
+If an existing Rails ingress has already stored an email, attach that record:
+
+```ruby
+MailboxKit::Mailboxes.for_tenant(trusted_tenant_key) do |session|
+  membership = session.attach(
+    recipient: verified_envelope_recipient,
+    inbound_email_id: inbound_email.id
+  )
+end
+```
+
+The caller must authorize the inbound ID and select its tenant before loading
+records. Do not pass an ID from another tenant or accept an unscoped ID from a
+customer. Attachment checks active address ownership, looks up the Rails record
+in the current connection, and rejects existing membership in another tenant.
+It is idempotent for the inbox/email pair and does not enqueue processing again.
+Aliases into the same inbox share a membership, retaining the first recipient.
+
+Use Rails' normal `ApplicationMailbox` routing and processing callbacks. One
+handler can dynamically resolve many organizations/sites; no class per inbox is
+needed. Default Rails routes match message headers and choose the first handler;
+they do not establish trusted tenant entitlement or automatically fan out into
+every recipient's inbox. Select a tenant before initial storage if raw mail lives
+in separate tenant databases. Attaching later cannot relocate that original row.
+
+## Receive source through a verified integration
+
+Your ingress adapter must authenticate the request and extract the actual SMTP
+envelope recipient before invoking the core. Do not route on an untrusted MIME
+`To` header or a customer-supplied tenant key.
+
+```ruby
+inbound_email = MailboxKit::Mailboxes.receive(
+  recipient: verified_envelope_recipient,
+  source: raw_mime
+)
+```
+
+The core resolves an active domain and address, selects the tenant, and records
+the mailbox membership in the same database transaction as Rails persistence.
+It calls Rails' creation API and returns the existing record on duplicate source.
+Identical source within one tenant can belong to multiple inboxes without creating
+another raw email or routing job. Default source identity includes the tenant
+scope and uses a stable fallback for missing Message-ID; identical bytes in a
+different tenant do not suppress that tenant's processing. MIME is not rewritten.
+The adapter remains responsible for authentication, authoritative envelope
+recipients, delivery-specific identity where necessary, and retrying failed
+requests. ActionMailbox still owns processing and its `ApplicationMailbox` routes.
+
+For application checks before persistence, the existing block form remains:
+
+```ruby
+require "mailbox_kit/inbound_email"
+MailboxKit::Mailboxes.receive(recipient: verified_envelope_recipient) do |destination|
+  MyAcceptancePolicy.check!(destination) # Application policy; raise to reject.
+  MailboxKit::InboundEmail.persist(source: raw_mime).record
+end
+```
+
+Blocks must return the existing Rails record on duplicates if membership should
+be attached. Rails' bare `create_and_extract_message_id!` returns `nil` for a
+duplicate, so using it directly in that block can omit a second inbox membership.
+Returning `nil` intentionally skips membership, preserving the older block API.
+Neither a database transaction nor source deduplication guarantees exactly-once
+business effects, external blob cleanup on rollback, or recovery of lost jobs.
+
+With Cloudflare, the adapter preserves its existing authenticated envelope and
+metadata-based delivery identity, then uses the same Rails persistence bridge:
+
+```ruby
+verified = Cloudflare::Email::Ingress.verify(
+  secret: ingress_secret, headers: request.headers, body: request.body
+)
+# Handle non-:ok verification results before accessing the verified message.
+verified.message.receive_into_mailbox! if verified.status == :ok
+```
+
+The shipped Cloudflare ingress controller already does this, including HTTP error
+handling and size limits. Installing the core does not add another HTTP endpoint
+or SMTP server. `persist_action_mailbox!` remains available for applications that
+only need Rails storage; its existing return convention is new record or `nil`
+on duplicate. The new inbox bridge can repair membership on duplicate delivery
+without rerouting the email or replacing stored authentication metadata.
+
+For an application with its own persistence, use
+`with_recipient(recipient:) { |destination| ... }`; it performs lookup and tenant
+selection without creating a message membership. It can run without ActionMailbox.
+
+An explicit pending/suspended address reserves its name: it never falls through
+to another inbox's catch-all. Unknown addresses are unavailable unless you
+explicitly enable a verified catch-all address with `session.enable_catch_all`.
+
+```ruby
+MailboxKit::Mailboxes.for_tenant("workspace") do |session|
+  messages = session.messages(inbox_id).inbox.unread
+  session.mark_read(inbox_id, message_id)
+  session.archive(inbox_id, message_id)
+  session.suspend(inbox_id) # Reversible; reserves existing addresses.
+end
+```
+
+## Retention is a Rails policy
+
+To retain all inbound mail, Rails already provides:
+
+```ruby
+config.action_mailbox.incinerate = false
+```
+
+Or configure its automatic cleanup interval with
+`config.action_mailbox.incinerate_after = 90.days`. Disabling scheduling does not
+cancel incineration jobs already queued. Rails normally schedules processed mail
+for cleanup after 30 days; pending mail is not processed mail.
+
+For apps that mix inboxes and transient email handlers, the kit adds a narrow
+membership guard through Rails' `action_mailbox_inbound_email` load hook: mail
+associated with an inbox survives normal incineration, while unassociated mail
+uses Rails' policy. `purge_message` explicitly removes membership and deletes raw
+mail only when no mailbox memberships remain. Attach, purge and this guard lock
+the same inbound row. Direct application deletion and external storage expiration
+remain the application's responsibility. ActionMailbox, ActiveStorage and mailbox
+records must share a connection for the transactional membership operations.
+
+## Management interface
+
+Require the optional engine in `config/application.rb`, before Rails initializes:
+
+```ruby
+require "mailbox_kit/management"
+```
+
+Mount it in `config/routes.rb`:
+
+```ruby
+mount MailboxKit::Management::Engine => "/mailboxes"
+```
+
+Configure `MailboxKit::Management.configure { |c| c.adapter = ->(controller) {
+MailboxAccess.new(controller) } }` in an initializer. `MailboxAccess` subclasses
+`MailboxKit::Management::Adapter` and supplies:
+
+- `authenticate!`: authenticate using the host application's session.
+- `tenant_key`: select a trusted scope for that principal.
+- `mailboxes(session)`: return only mailboxes the principal can access.
+- `allowed?(action, mailbox = nil)`: authorize each operation.
+- `domains(session)`: return domains the principal may use.
+
+All defaults deny access. The engine intersects your relation with its tenant
+scope and checks permissions again for each action. Override `create_mailbox` and
+`add_address` to attach your ownership policy. Ownership alone never grants access.
+The UI needs no React, Inertia, or frontend build. It shows safe text previews;
+remote images and arbitrary email HTML are not rendered.
+
+## Optional database tenancy
+
+Before requiring mailbox models, configure your application's connection switch:
+
+```ruby
+require "mailbox_kit/tenancy"
+MailboxKit::Tenancy.configure(
+  base_class: TenantRecord,
+  switch: ->(key, &block) { TenantRecord.with_tenant(key, &block) },
+  current: -> { TenantRecord.current_tenant }
+)
+require "mailbox_kit/mailboxes/configuration"
+MailboxKit::Mailboxes.configure(directory_base: SharedRecord)
+require "mailbox_kit/mailboxes"
+```
+
+Those host methods are examples; adapt them to your tenancy library. Run directory
+migrations on the shared database and mailbox migrations on each tenant database
+using the generator's `--directory-migrations-path` and `--tenant-migrations-path`.
+Never choose the tenant from request parameters. Rails framework jobs preserve the
+explicit context; your own tenant jobs can `prepend MailboxKit::TenantJobContext`
+after requiring `mailbox_kit/tenant_job_context`.
+
+## Existing Cloudflare Email applications
+
+Keep your existing requires, initializer, migrations, Worker and mounted engine.
+Updating the Cloudflare gem brings in this core as a dependency. Public Cloudflare
+constants resolve to the same core models; tables, IDs and tenant job payload keys
+are retained. The `cloudflare_email_` table prefix is intentionally unchanged.
+Do **not** run `mailbox_kit:install` over an existing Cloudflare mailbox schema.
+
+For a fresh Cloudflare application, continue using the Cloudflare mailbox generator,
+which also installs its outbox and event tables. A core-only installation should
+not run both installers; adding Cloudflare outbound later needs its additional
+tables and explicit sending-account/domain configuration. The receiving-only core
+does not automatically become a Cloudflare sending account when the adapter loads.
+
+## Sending from customer subdomains
+
+Cloudflare onboards each sending domain/subdomain separately. Parent-domain
+verification and wildcard receiving do not authorize arbitrary From subdomains.
+Use an explicitly verified sending domain and, where useful, a customer-specific
+inbound Reply-To. See [Cloudflare's subdomain rules](https://developers.cloudflare.com/email-service/configuration/subdomains/).
+
+## Development and release
+
+From the repository root, `bundle exec rake test` exercises both the compatibility
+API and standalone core. `bundle exec ruby script/verify_package.rb` builds both
+archives, installs a Rails-free consumer, and tests the packaged Rails integrations.
+Publish `mailbox-kit` before releasing a Cloudflare version that depends on it.

data/docs/upgrading.md

@@ -0,0 +1,60 @@
+# Upgrading existing mailbox installations
+
+The extracted core keeps existing `cloudflare_email_` tables, record IDs, public
+Cloudflare constants and tenant job payloads. Keep your initializer, mounted
+engine, Worker and application processing code. Do not run `mailbox_kit:install`
+or the Cloudflare mailbox installer over existing mailbox tables.
+
+After updating the gems, generate the index and receiving-domain migrations:
+
+```sh
+bin/rails generate mailbox_kit:upgrade
+bin/rails db:migrate
+```
+
+For separate tenant databases:
+
+```sh
+bin/rails generate mailbox_kit:upgrade --tenant-migrations-path=db/tenant_migrate --directory-migrations-path=db/migrate
+```
+
+Apply the index migration to every database containing mailbox messages using your
+application's tenant migration runner. It does not belong in the shared domain
+directory database. The migration preserves messages and skips an existing
+single-column inbound index. New installers already include this index.
+
+Apply `AllowProviderNeutralReceivingDomains` to the shared directory database.
+It allows a null receiving-domain account ID, preserving existing account values.
+Receiving-only registration requires no Cloudflare account; sending still requires
+an explicit account and verified sending domain. On SQLite this schema change can
+rebuild the directory table, so use your normal migration window.
+
+Index creation can block writes on large tables. Plan its application according
+to your database's normal migration procedure; PostgreSQL installations needing
+online builds can adapt it to `algorithm: :concurrently` with
+`disable_ddl_transaction!`.
+
+## Verify the application upgrade
+
+1. Receive a message through the existing authenticated provider integration.
+2. Confirm it appears in the right inbox and runs the existing business handler.
+3. Replay the delivery and confirm no duplicate business effects.
+4. Check authorized and unauthorized UI access, read/archive actions, and retention.
+5. For separate databases, exercise tenant routing and processing jobs in two tenants.
+
+Keep your application's sender acceptance, ownership reconciliation and processing
+claims. Rails processing status does not replace these business policies.
+
+## Adding Cloudflare to a core-only application
+
+The core's mailbox schema alone does not supply Cloudflare's outbox and event
+tables. Add those provider tables and sending configuration explicitly using the
+Cloudflare integration guide; do not run both complete installers against the
+same database. Arbitrary subdomain receiving does not authorize sending from those
+subdomains: verify each Cloudflare sending domain separately.
+
+## Versions
+
+Cloudflare Email 0.4.0 depends on Mailbox Kit 0.1.x and installs it automatically.
+Core-only applications can install `gem "mailbox-kit", "~> 0.1.0"` directly.
+Upgrade and verify your application's email flows before a wider rollout.

data/lib/generators/mailbox_kit/install/install_generator.rb

@@ -0,0 +1,24 @@
+require "rails/generators"
+require "rails/generators/active_record"
+module MailboxKit
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      include ::ActiveRecord::Generators::Migration
+      namespace "mailbox_kit:install"
+      source_root File.expand_path("templates", __dir__)
+      class_option :tenant_migrations_path, type: :string, default: "db/migrate"
+      class_option :directory_migrations_path, type: :string, default: "db/migrate"
+      def copy_migrations
+        migration_template "create_mailbox_kit_receiving_domains.rb", File.join(options[:directory_migrations_path], "create_mailbox_kit_receiving_domains.rb")
+        migration_template "create_mailbox_kit_mailboxes.rb", File.join(options[:tenant_migrations_path], "create_mailbox_kit_mailboxes.rb")
+      end
+      def create_initializer
+        create_file "config/initializers/mailbox_kit.rb", <<~RUBY
+          # Single database by default. Configure MailboxKit::Tenancy before
+          # requiring mailbox models when using separate tenant databases.
+          require "mailbox_kit/mailboxes"
+        RUBY
+      end
+    end
+  end
+end

data/lib/generators/mailbox_kit/install/templates/create_mailbox_kit_mailboxes.rb

@@ -0,0 +1,51 @@
+class CreateMailboxKitMailboxes < 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, :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"
+
+  end
+
+  def down
+    raise ActiveRecord::IrreversibleMigration, "Preserve mailbox ownership and retained messages; use a forward fix"
+  end
+end

data/lib/generators/mailbox_kit/install/templates/create_mailbox_kit_receiving_domains.rb

@@ -0,0 +1,16 @@
+class CreateMailboxKitReceivingDomains < 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 # Optional adapter compatibility; not a mailbox provider identity.
+      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/mailbox_kit/upgrade/templates/allow_provider_neutral_receiving_domains.rb

@@ -0,0 +1,9 @@
+class AllowProviderNeutralReceivingDomains < ActiveRecord::Migration[7.1]
+  def up
+    change_column_null :cloudflare_email_receiving_domains, :account_id, true
+  end
+
+  def down
+    raise ActiveRecord::IrreversibleMigration, "Receiving-only domains need no provider account; use a forward fix"
+  end
+end

data/lib/generators/mailbox_kit/upgrade/templates/index_mailbox_kit_inbound_messages.rb

@@ -0,0 +1,12 @@
+class IndexMailboxKitInboundMessages < ActiveRecord::Migration[7.1]
+  def up
+    return if index_exists?(:cloudflare_email_mailbox_messages, :inbound_email_id)
+
+    add_index :cloudflare_email_mailbox_messages, :inbound_email_id,
+      name: "idx_cf_email_message_inbound"
+  end
+
+  def down
+    raise ActiveRecord::IrreversibleMigration, "Preserve the inbound lookup index; use a forward fix"
+  end
+end

data/lib/generators/mailbox_kit/upgrade/upgrade_generator.rb

@@ -0,0 +1,23 @@
+require "rails/generators"
+require "rails/generators/active_record"
+
+module MailboxKit
+  module Generators
+    class UpgradeGenerator < ::Rails::Generators::Base
+      include ::ActiveRecord::Generators::Migration
+      namespace "mailbox_kit:upgrade"
+      source_root File.expand_path("templates", __dir__)
+      class_option :tenant_migrations_path, type: :string, default: "db/migrate",
+        desc: "Migration directory applied to each database containing mailbox messages"
+      class_option :directory_migrations_path, type: :string, default: "db/migrate",
+        desc: "Migration directory for the shared receiving-domain directory"
+
+      def copy_migration
+        migration_template "index_mailbox_kit_inbound_messages.rb",
+          File.join(options[:tenant_migrations_path], "index_mailbox_kit_inbound_messages.rb")
+        migration_template "allow_provider_neutral_receiving_domains.rb",
+          File.join(options[:directory_migrations_path], "allow_provider_neutral_receiving_domains.rb")
+      end
+    end
+  end
+end

data/lib/mailbox-kit.rb

@@ -0,0 +1,11 @@
+require "mailbox_kit/version"
+require "mailbox_kit/error"
+
+module MailboxKit
+  ROOT = File.expand_path("..", __dir__).freeze
+  module Mailboxes
+    def self.enabled? = @enabled == true
+  end
+end
+
+require "mailbox_kit/railtie" if defined?(::Rails::Railtie)

data/lib/mailbox_kit/active_record/base.rb

@@ -0,0 +1,58 @@
+require "active_record"
+require "mailbox_kit/tenancy"
+
+module MailboxKit
+  module ActiveRecord
+    # Rails may inspect every model's pool while preloading schema metadata
+    # before any request has selected a tenant. Report an unavailable
+    # connection using Rails' error hierarchy so boot can recover, while
+    # retaining the same fail-closed guard for every caller.
+    class TenantConnectionUnavailable < ::ActiveRecord::ConnectionNotEstablished; end
+
+    # Uses the host's abstract tenant connection owner when explicitly configured.
+    class Base < Tenancy.model_base(::ActiveRecord::Base)
+      self.abstract_class = true
+
+      class << self
+        def connection_pool
+          if Tenancy.enabled?
+            begin
+              Tenancy.require_context!
+            rescue ConfigurationError => error
+              raise TenantConnectionUnavailable, error.message
+            end
+          end
+          super
+        end
+      end
+
+      before_validation :verify_cloudflare_email_tenant!
+      before_save :verify_cloudflare_email_tenant!
+      before_destroy :verify_cloudflare_email_tenant!
+
+      # These methods can bypass callbacks or load a different row with the same ID.
+      %i[reload update_columns delete touch increment! decrement! association].each do |method_name|
+        define_method(method_name) do |*args, **kwargs, &block|
+          verify_cloudflare_email_tenant!
+          super(*args, **kwargs, &block)
+        end
+      end
+
+      private
+
+      # Both new construction and persisted-row instantiation call this before
+      # assigning inverse associations (which precede after_initialize).
+      def init_internals
+        super
+        @cloudflare_email_tenant_key = Tenancy.require_context! if Tenancy.enabled?
+      end
+
+      def verify_cloudflare_email_tenant!
+        return unless Tenancy.enabled?
+        unless @cloudflare_email_tenant_key == Tenancy.require_context!
+          raise ConfigurationError, "record belongs to a different tenant context"
+        end
+      end
+    end
+  end
+end

data/lib/mailbox_kit/address_syntax.rb

@@ -0,0 +1,19 @@
+module MailboxKit
+  module AddressSyntax
+      LOCAL_PART = /\A[A-Za-z0-9.!#$%&'*+\/=\?^_`{|}~-]+\z/
+      DOMAIN_LABEL = /\A[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?\z/
+
+      def self.valid_address?(address, allow_empty: false)
+        return false unless address.is_a?(String) && address.ascii_only?
+        return true if allow_empty && address.empty?
+        return false if address.bytesize > 254
+        parts = address.split("@", -1)
+        return false unless parts.size == 2
+        local, domain = parts
+        local.bytesize <= 64 && LOCAL_PART.match?(local) &&
+          !local.start_with?(".") && !local.end_with?(".") && !local.include?("..") &&
+          domain.split(".", -1).all? { |label| DOMAIN_LABEL.match?(label) }
+      end
+
+  end
+end

data/lib/mailbox_kit/error.rb

@@ -0,0 +1,14 @@
+module MailboxKit
+  class Error < StandardError
+    attr_reader :response, :status
+
+    def initialize(message = nil, status: nil, response: nil)
+      super(message)
+      @status   = status
+      @response = response
+    end
+  end
+
+  class ConfigurationError < Error; end
+  class ValidationError < Error; end
+end

data/lib/mailbox_kit/inbound_email.rb

@@ -0,0 +1,56 @@
+require "mailbox-kit"
+require "digest"
+
+module MailboxKit
+  # A small bridge to Rails' existing storage and routing lifecycle. It returns
+  # the existing record on duplicate delivery so callers can attach memberships.
+  module InboundEmail
+    Result = Struct.new(:record, :created, keyword_init: true) do
+      def created? = created
+    end
+
+    def self.persist(source:, message_id: nil, message_checksum: nil, metadata: {})
+      unless defined?(::ActionMailbox::InboundEmail)
+        raise ConfigurationError, "load ActionMailbox before persisting inbound mail"
+      end
+      raise ArgumentError, "source must be a String" unless source.is_a?(String)
+      source = source.b
+      scope = Tenancy.require_context! if defined?(Tenancy) && (Tenancy.enabled? || Tenancy.current_key)
+      # Two tenant scopes can share a database. Sharing bytes must not suppress
+      # the other tenant's Rails routing job. Recipients within one scope can
+      # share the same record and have independent inbox memberships.
+      checksum = message_checksum || if scope
+        Digest::SHA256.new.update("mailbox-kit\0#{scope.bytesize}:#{scope}\0").update(source).hexdigest
+      else
+        Digest::SHA1.hexdigest(source)
+      end
+      unless message_id
+        message_id = begin
+          ::Mail.from_source(source).message_id
+        rescue StandardError
+          nil
+        end
+      end
+      identity = { message_id: message_id || "#{checksum}@mailbox-kit.invalid",
+                   message_checksum: checksum }
+      model = ::ActionMailbox::InboundEmail
+      model.transaction do
+        if (existing = model.find_by(identity))
+          next Result.new(record: existing, created: false).freeze
+        end
+        # Rails returns nil on a unique conflict. Roll back that savepoint before
+        # looking up the winner, including on PostgreSQL's aborted transactions.
+        record = model.transaction(requires_new: true) do
+          created = model.create_and_extract_message_id!(source, **identity)
+          raise ::ActiveRecord::Rollback unless created
+          unless metadata.empty?
+            blob = created.raw_email.blob
+            blob.update!(metadata: blob.metadata.merge(metadata))
+          end
+          created
+        end
+        Result.new(record: record || model.find_by!(identity), created: !record.nil?).freeze
+      end
+    end
+  end
+end

data/lib/mailbox_kit/mailboxes/configuration.rb

@@ -0,0 +1,19 @@
+require "active_record"
+require "mailbox_kit/error"
+module MailboxKit
+  module Mailboxes
+    class Unavailable < MailboxKit::Error; end
+    class << self
+      def configure(directory_base: ::ActiveRecord::Base)
+        raise ConfigurationError, "configure mailboxes before loading mailbox models" if const_defined?(:ReceivingDomain, false)
+        unless directory_base.is_a?(Class) && directory_base <= ::ActiveRecord::Base
+          raise ConfigurationError, "directory_base must be an ActiveRecord base class"
+        end
+        @directory_base = directory_base
+      end
+      def directory_base = @directory_base || ::ActiveRecord::Base
+      def enabled? = @enabled == true
+      def enable! = @enabled = true
+    end
+  end
+end