posthaste-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a5665a5f083a24bc3da1115e38819ab66e4ee5c956910ec91af8b9d4ae8724ba
+  data.tar.gz: f728072cd752a9cd152581235f87d8b158fa9f8067ff8cb05e573d8aeaa261a1
+SHA512:
+  metadata.gz: 866027847539374855f77ebf62aa7411b1ea2ceb22015743e646f78d7e5258024d2987bb619b3f249d40634b568e060383eaf36e40f2382001c8b3636a5ddd82
+  data.tar.gz: c6de9eadc6a60c2af4c365f315ff4179e3bfd518a069f5cfc6ef0fd62d99ead7989f86f18260efeba66ff76b007b6120d2c6473b49c24a0bbea656eba70eadf8

data/LICENSE

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

data/README.md

@@ -0,0 +1,323 @@
+# posthaste-rails
+
+An ActionMailer delivery method for the [Posthaste](https://posthastemail.dev)
+transactional email API.
+
+If your application already sends mail with ActionMailer, the whole migration is
+two lines of configuration. Every `mail()` call, every view, every
+`deliver_later`, every `assert_emails` in your test suite stays exactly as it is.
+
+```ruby
+# Gemfile
+gem 'posthaste-rails'
+```
+
+```ruby
+# config/environments/production.rb
+config.action_mailer.delivery_method = :posthaste
+config.action_mailer.posthaste_settings = { api_key: ENV['POSTHASTE_API_KEY'] }
+```
+
+That is the change. Nothing else in the application moves.
+
+Requires Ruby 3.1+ and ActionMailer 6.1+. Its only dependency is ActionMailer
+itself — the HTTP is `Net::HTTP` and the JSON is the stdlib, so it adds nothing
+to your lockfile that Rails was not already carrying.
+
+## Why this and not SMTP
+
+Posthaste runs an [SMTP relay](https://posthastemail.dev/docs/smtp), and
+ActionMailer can point at it today with no gem at all. That is a perfectly good
+answer, so here is the honest comparison rather than a pitch.
+
+| Reach for      | When                                                                                                                                                                                                       |
+| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| The SMTP relay | You are on an ordinary server or container, port 587 is open outbound, and you send ordinary mail — including things this adapter cannot express, like calendar invitations.                               |
+| This gem       | Outbound SMTP is blocked or throttled where you run. Most serverless and container platforms either block 25/587 outright or make a long-lived connection expensive; an HTTPS request has neither problem. |
+| This gem       | You want the fields SMTP has nowhere to put: streams, tags, metadata, stored templates, an idempotency key, scheduled sending.                                                                             |
+| This gem       | You want to branch on _why_ a message was refused. SMTP gives you a three-digit code and a sentence.                                                                                                       |
+
+## Settings
+
+Everything is optional except the key, which falls back to `POSTHASTE_API_KEY`.
+
+```ruby
+config.action_mailer.posthaste_settings = {
+  api_key:         ENV['POSTHASTE_API_KEY'],
+  base_url:        'https://api.posthastemail.dev', # self-hosting? point it here
+  stream:          'transactional',                 # default for every message
+  tags:            %w[rails],
+  metadata:        { app: 'acme' },
+  open_timeout:    10,
+  read_timeout:    30,
+  max_retries:     2,
+  max_retry_delay: 60.0,
+  on_warning:      ->(w) { Rails.logger.warn("[posthaste] #{w}") },
+  logger:          Rails.logger,
+}
+```
+
+An unrecognised setting raises `Posthaste::ConfigurationError` naming it, rather
+than being ignored — a typo like `api_kye:` is otherwise a silent fallback to
+the environment variable, or to no key at all.
+
+`base_url` is the whole story for a self-hosted install: point it at your own
+API host and everything else works unchanged.
+
+## Reading the result
+
+`deliver_now` hands back the `Mail::Message`, as it always has. The API's answer
+is attached to it:
+
+```ruby
+mail = InvoiceMailer.issued(invoice).deliver_now
+
+mail.posthaste_result.id           # 'msg_AZLm3kQ8T2Sf9pXbNc7HrQ'
+mail.posthaste_result.status       # 'queued' | 'scheduled' | 'duplicate'
+mail.posthaste_result.duplicate?   # an idempotency replay: no new message exists
+mail.posthaste_result.suppressed   # recipients skipped, and why
+mail.posthaste_result.warnings     # the platform's pre-send lint findings
+mail.posthaste_result.mapping_warnings # what this gem had to change
+```
+
+`#posthaste_result` is the only method this gem adds to a class it does not own.
+It returns `nil` for a message delivered any other way.
+
+## The fields ActionMailer has no word for
+
+Streams, tags, metadata, idempotency keys, stored templates and scheduled sends
+are set with `X-Posthaste-…` headers. `mail()` already passes any unrecognised
+key straight through as a header, so this needs no new API and works in every
+Rails version:
+
+```ruby
+def issued(invoice)
+  mail(
+    to: invoice.email,
+    subject: "Invoice #{invoice.number}",
+    'X-Posthaste-Stream' => 'transactional',
+    'X-Posthaste-Tags' => 'invoice,billing',
+    'X-Posthaste-Metadata' => { invoice_id: invoice.id }.to_json,
+    'X-Posthaste-Idempotency-Key' => "invoice-#{invoice.id}",
+  )
+end
+```
+
+| Header                         | Becomes           | Notes                                         |
+| ------------------------------ | ----------------- | --------------------------------------------- |
+| `X-Posthaste-Stream`           | `stream`          | Defaults to the settings-level `stream`.      |
+| `X-Posthaste-Tags`             | `tags`            | Comma-separated.                              |
+| `X-Posthaste-Metadata`         | `metadata`        | A JSON object. Values are coerced to strings. |
+| `X-Posthaste-Idempotency-Key`  | `idempotencyKey`  | See _Retries_ below.                          |
+| `X-Posthaste-Template`         | `template`        | The stored template supplies the body.        |
+| `X-Posthaste-Template-Version` | `templateVersion` | An integer.                                   |
+| `X-Posthaste-Variables`        | `variables`       | A JSON object.                                |
+| `X-Posthaste-Scheduled-At`     | `scheduledAt`     | RFC 3339, e.g. `2026-09-01T09:00:00Z`.        |
+
+They are **consumed**: none of them reach the wire as ordinary headers. A
+mistyped one (`X-Posthaste-Steam`) raises rather than being forwarded as an
+inert custom header, because the alternative is a send that quietly ignores the
+stream it was told to use.
+
+## What maps, what changes, what is refused
+
+ActionMailer hands the delivery method a fully-composed `Mail::Message` — a rich
+RFC 5322 document. The send API takes _fields_. The governing rule for the gap
+between them is that **nothing is dropped in silence**: a team that migrates and
+does not notice their Bcc stopped arriving is the outcome this design exists to
+prevent.
+
+### Mapped, unchanged
+
+| ActionMailer                             | Becomes                                                                                                                                                                                |
+| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `from`                                   | `from`, display name kept                                                                                                                                                              |
+| `to`, `cc`, `bcc`                        | `to`, `cc`, `bcc` — each recipient is its own message and counts as one send                                                                                                           |
+| `reply_to`                               | `replyTo`, display names kept, several addresses kept                                                                                                                                  |
+| `subject`                                | `subject`                                                                                                                                                                              |
+| text and HTML templates                  | `text` and `html`, found wherever the message put them — including `multipart/mixed[ multipart/alternative[…], attachment ]`, which is what Rails builds for two templates plus a file |
+| a single-template, non-multipart message | `text`, or `html` if its Content-Type says so                                                                                                                                          |
+| `attachments[…]`                         | `attachments`, base64-encoded, with the declared content type                                                                                                                          |
+| `attachments.inline[…]`                  | `attachments` with `disposition: inline` and the `cid` kept, so `<img src="cid:…">` still resolves                                                                                     |
+| `List-Unsubscribe`                       | `listUnsubscribe`                                                                                                                                                                      |
+| any other header                         | `headers`                                                                                                                                                                              |
+
+### Mapped, with a warning
+
+Warnings reach `on_warning` and `mail.posthaste_result.mapping_warnings`, so you
+find out on the first send rather than in a support ticket.
+
+| What                                             | What happens                                                | Why                                                                                                                                                                                                                                                                                                                                                               |
+| ------------------------------------------------ | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Display names on `to` / `cc` / `bcc`             | The name is dropped; the address is unchanged.              | The API addresses recipients by bare address. This is the one place the mapping loses something a recipient could have seen — and it is only how their own address is labelled in their own client, which most clients override from the address book anyway. Refusing would break the migration for nearly every application that has ever set a recipient name. |
+| A body whose declared charset does not decode    | Unreadable bytes are replaced.                              | The message still goes; the damage is confined to bytes that were already unreadable.                                                                                                                                                                                                                                                                             |
+| `X-Posthaste-Template` alongside a rendered view | The template supplies the content and the view is not sent. | Sending both would make the API pick one, and whichever it picked would be a surprise.                                                                                                                                                                                                                                                                            |
+
+### Composed by the platform, and dropped without a warning
+
+`Date`, `Message-ID`, `MIME-Version`, `Content-Type`,
+`Content-Transfer-Encoding`, `Content-Disposition`, `List-Unsubscribe-Post`.
+
+Mail stamps every one of these onto every message before a delivery method ever
+sees it, so a warning here would fire on every send an application ever made —
+which is exactly how the warnings that matter get ignored. The platform composes
+the MIME and signs the identity headers itself; the bytes the recipient's client
+decodes are the same either way.
+
+### Refused, before the request is made
+
+Each of these raises a `Posthaste::MappingError` naming the field, rather than
+sending a message that is quietly missing something.
+
+| What                                                                                                            | Why                                                                                                                                                                                                                                                           |
+| --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Sender`, `Return-Path`, `DKIM-Signature`, `Received`, `Authentication-Results`, `Feedback-ID`, `ARC-*`         | The platform writes and DKIM-signs these. A second copy either duplicates a signed header — some receivers reject two `From`s — or drifts from the signed value and fails DMARC. `Feedback-ID` in particular is the key Google aggregates complaint rates by. |
+| The same custom header set twice                                                                                | The API carries one value per header name, and keeping one of the two would be a silent choice about which the recipient sees.                                                                                                                                |
+| A `from` that parses to more than one address                                                                   | Almost always an unquoted comma: `from: "Acme, Inc. <billing@acme.test>"` is _two_ addresses to any RFC 5322 parser. Quote it: `from: %q("Acme, Inc." <billing@acme.test>)`.                                                                                  |
+| A part that is neither body nor named attachment — a `text/calendar` invitation, an attachment with no filename | Mail identifies an attachment _by its filename_, so these are not in `mail.attachments` at all and would vanish between here and the wire. Give it a filename, or use the SMTP relay, which accepts a complete MIME message.                                  |
+| A message with no `to`                                                                                          | There is nobody to send it to.                                                                                                                                                                                                                                |
+
+## Refusals are typed
+
+A suppressed recipient, an unverified domain and an exhausted quota are three
+different problems with three different fixes. One generic error is what makes
+an integration miserable to debug.
+
+```ruby
+begin
+  InvoiceMailer.issued(invoice).deliver_now
+
+rescue Posthaste::SuppressedError => e
+  # Never work around this. Sending to a suppressed address is how a sending IP
+  # gets blocklisted, and the block lands on everyone sharing it.
+  stop_mailing(e.suppression.address, e.suppression.reason)   # 'complaint'
+
+rescue Posthaste::DomainNotVerifiedError
+  # Publish the DKIM record and verify the domain. There is no flag for this.
+  alert_ops!
+
+rescue Posthaste::QuotaExhausted => e
+  # Hours or days, not seconds. Queue it or alert — do NOT sleep.
+  Retry.tomorrow(invoice, after: e.retry_after_seconds)
+
+rescue Posthaste::RateLimited => e
+  # Transient, and it clears on its own.
+  Retry.in(e.retry_after_seconds || 60, invoice)
+
+rescue Posthaste::ContentBlockedError => e
+  # The whole lint report, warnings included, so one fix pass covers everything.
+  Rails.logger.error([e.check, e.findings].inspect)
+end
+```
+
+```
+Posthaste::Error
+├── Posthaste::ConfigurationError      no key, or an unknown setting
+├── Posthaste::MappingError            the message cannot be expressed
+│   └── Posthaste::UnsupportedHeaderError
+├── Posthaste::ConnectionError         never reached the server (status 0)
+│   └── Posthaste::TimeoutError
+└── Posthaste::APIStatusError
+    ├── Posthaste::AuthenticationError    401
+    ├── Posthaste::PermissionDeniedError  403 — a real key without emails:send
+    ├── Posthaste::InvalidRequestError    400
+    ├── Posthaste::NotFoundError          404
+    ├── Posthaste::ConflictError          409
+    ├── Posthaste::UnprocessableError     422 — permanent, never retried
+    │   ├── Posthaste::SuppressedError
+    │   ├── Posthaste::DomainNotVerifiedError
+    │   ├── Posthaste::ContentBlockedError
+    │   ├── Posthaste::AttachmentError
+    │   ├── Posthaste::ScheduleError
+    │   ├── Posthaste::TemplateError
+    │   └── Posthaste::StreamError
+    ├── Posthaste::RateLimited            429 — transient
+    ├── Posthaste::QuotaExhausted         429 — a SIBLING, never a subclass
+    └── Posthaste::ServerError            5xx
+```
+
+`QuotaExhausted` being a sibling of `RateLimited` rather than a subclass is
+deliberate. All four of the API's 429s look identical at the status level, and
+they are not: `rate_limited` and `platform_paused` clear in seconds, while
+`daily_limit_reached` and `monthly_limit_reached` clear when the calendar moves.
+A `rescue Posthaste::RateLimited` that slept would sleep for a week.
+
+Branch on `error.type` — a stable machine-readable string — never on the
+message. An `error.type` this version has never seen is not a bug: the API is
+allowed to add refusal reasons, and an unknown one becomes the class its status
+implies rather than being mistaken for a documented one.
+`Posthaste::KNOWN_ERROR_TYPES` is the list this version knows.
+
+`raise_delivery_errors = false` still swallows all of it, because this is a real
+ActionMailer delivery method and `Mail::Message#do_delivery` is what rescues.
+
+## Retries
+
+A failed send is repeated automatically **only when it carries an idempotency
+key**, because without one a retry after a lost response sends the email twice.
+For a mail API that is not a performance detail; it is the difference between
+one invoice and two.
+
+Set `X-Posthaste-Idempotency-Key` and you get two retries with exponential
+backoff and full jitter, honouring `Retry-After` up to `max_retry_delay`
+(60 seconds by default) and never retrying an exhausted quota. Beyond that
+ceiling the error comes back so you can schedule it rather than blocking a web
+request.
+
+The key is a **body field**, not the `Idempotency-Key` HTTP header. The header is
+in the API's CORS allowlist but no handler reads it, so a client that sends the
+header and not the field gets no idempotency at all and no warning that it has
+none. This gem never sends the header.
+
+## The API key
+
+The key is a bearer credential: whoever holds it can send from every verified
+domain on the account. It escapes through the places nobody guards — Ruby's
+default `#inspect` prints every instance variable, and Rails' exception page, a
+`binding.irb` pasted into a ticket, and an error reporter capturing locals all
+call it on your behalf.
+
+So every object here defines its own `#inspect`, and every string built for a
+human goes through a redactor first:
+
+```ruby
+ActionMailer::Base.delivery_method  # => :posthaste
+mailer.message.delivery_method.inspect
+# => #<Posthaste::DeliveryMethod api_key="ph_test_***redacted***" …>
+```
+
+The environment prefix is kept because it is not secret — it is printed beside
+every key in the dashboard — and it is the one piece that tells somebody staring
+at a 401 that they pasted the test key into production. It is deliberately _not_
+the usual last-four-characters convention: four characters of a token this size
+cannot authenticate, but they are enough to confirm a guess.
+
+Server messages are redacted too, in two passes: this client's own key, and then
+anything key-shaped, which catches a _different_ account's key echoed back by a
+proxy that quoted the request line.
+
+## Testing your own mailers
+
+Nothing changes. `delivery_method = :test`, `ActionMailer::Base.deliveries` and
+`assert_emails` all keep working, because this is a delivery method registered
+through ActionMailer's own `add_delivery_method` rather than a replacement for
+any part of it.
+
+To drive this gem in a test without a network, pass a `transport:` — anything
+that responds to `call(method, url, headers, body)` and returns a
+`Posthaste::Response`.
+
+## Running this gem's own tests
+
+```
+cd packages/actionmailer-ruby
+ruby -Ilib -Itest -e 'Dir["test/**/*_test.rb"].each { |f| require "./#{f}" }'
+```
+
+The suite never makes a real network call and never sends real mail: `Net::HTTP`
+is poisoned in `test_helper.rb`, and every address in the package is under an
+RFC 2606 reserved domain, enforced by `no_real_recipients_test.rb`.
+
+## Licence
+
+MIT.

data/lib/posthaste/actionmailer.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+# posthaste-rails — send ActionMailer mail through the Posthaste transactional
+# email API.
+#
+#   # config/environments/production.rb
+#   config.action_mailer.delivery_method = :posthaste
+#   config.action_mailer.posthaste_settings = { api_key: ENV['POSTHASTE_API_KEY'] }
+#
+# That is the whole migration. Every `mail()` call, every view, every
+# `deliver_later`, every `assert_emails` in your test suite stays as it is,
+# because this registers a delivery method through ActionMailer's own
+# `add_delivery_method` rather than replacing anything.
+#
+# The fields the send API has and ActionMailer has no word for — streams, tags,
+# metadata, idempotency keys, stored templates, scheduled sending — are set with
+# `X-Posthaste-…` headers on the message, which `mail()` already passes through
+# untouched. See the README.
+
+require 'active_support/lazy_load_hooks'
+
+require_relative 'delivery_method'
+require_relative 'errors'
+require_relative 'http_client'
+require_relative 'message_mapper'
+require_relative 'redaction'
+require_relative 'result'
+require_relative 'version'
+
+module Posthaste
+  # Register `:posthaste` with ActionMailer.
+  #
+  # Idempotent, and it has to be: `add_delivery_method` resets
+  # `posthaste_settings` to the default options, so calling it a second time
+  # after the application has configured its key would silently blank the key.
+  # The guard is `respond_to?`, because that accessor is exactly what
+  # `add_delivery_method` defines.
+  #
+  # @return [Boolean] true if this call did the registering
+  def self.register_delivery_method!(base = ::ActionMailer::Base)
+    return false if base.respond_to?(:posthaste_settings)
+
+    base.add_delivery_method(:posthaste, DeliveryMethod)
+    true
+  end
+
+  # Add `Mail::Message#posthaste_result`, once Mail is loaded.
+  def self.extend_mail_message!(klass = ::Mail::Message)
+    return false if klass.include?(MessageExtensions)
+
+    klass.include(MessageExtensions)
+    true
+  end
+end
+
+# The lazy hook, not an eager `require 'action_mailer'`.
+#
+# `on_load(:action_mailer)` fires when ActionMailer::Base is actually loaded —
+# in a Rails app that is during `action_mailer.set_configs`, and in a plain
+# script it is the moment somebody requires action_mailer. Requiring
+# ActionMailer here instead would drag the whole of ActionPack into the boot of
+# an application that has not asked for it yet.
+ActiveSupport.on_load(:action_mailer) do
+  Posthaste.register_delivery_method!(self)
+  Posthaste.extend_mail_message!
+end
+
+require_relative 'railtie' if defined?(::Rails::Railtie)

data/lib/posthaste/delivery_method.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require_relative 'errors'
+require_relative 'http_client'
+require_relative 'message_mapper'
+require_relative 'redaction'
+require_relative 'result'
+
+module Posthaste
+  # An ActionMailer delivery method.
+  #
+  # This is ActionMailer's own contract and nothing more: `add_delivery_method`
+  # registers a class, `wrap_delivery_behavior` instantiates it with the
+  # settings hash, and `Mail::Message#do_delivery` calls `deliver!(mail)`. That
+  # is why `perform_deliveries`, `raise_delivery_errors`, `deliver_later`, the
+  # `:test` delivery method, `assert_emails` and every interceptor and observer
+  # keep working untouched — none of them are our business, and a hand-rolled
+  # sender that bypassed `deliver!` would break all of them.
+  class DeliveryMethod
+    SETTING_KEYS = %i[
+      api_key base_url stream tags metadata open_timeout read_timeout
+      max_retries max_retry_delay transport logger on_warning
+    ].freeze
+
+    def initialize(settings = {})
+      settings = normalize(settings)
+      unknown = settings.keys - SETTING_KEYS
+      unless unknown.empty?
+        raise ConfigurationError.new(
+          "unknown posthaste_settings: #{unknown.map(&:inspect).join(', ')}. " \
+          "Known settings are: #{SETTING_KEYS.map(&:inspect).join(', ')}.",
+          type: 'configuration_error'
+        )
+      end
+
+      # Held in one place, and never in a hash that some other object's
+      # `#inspect` might print.
+      @api_key = (settings[:api_key] || ENV['POSTHASTE_API_KEY']).to_s
+      if @api_key.empty?
+        raise ConfigurationError.new(
+          'no Posthaste API key. Set `config.action_mailer.posthaste_settings = ' \
+          '{ api_key: … }` or the POSTHASTE_API_KEY environment variable.',
+          type: 'configuration_error'
+        )
+      end
+
+      @logger = settings[:logger]
+      @on_warning = settings[:on_warning]
+      @defaults = {
+        stream: settings[:stream],
+        tags: settings[:tags],
+        metadata: settings[:metadata]
+      }.compact
+
+      @client = HttpClient.new(
+        api_key: @api_key,
+        base_url: settings[:base_url] || DEFAULT_BASE_URL,
+        transport: settings[:transport],
+        max_retries: settings.fetch(:max_retries, HttpClient::DEFAULT_MAX_RETRIES),
+        max_retry_delay: settings.fetch(:max_retry_delay, HttpClient::DEFAULT_MAX_RETRY_DELAY),
+        open_timeout: settings.fetch(:open_timeout, 10),
+        read_timeout: settings.fetch(:read_timeout, 30)
+      )
+    end
+
+    # ActionMailer's delivery-method contract. Returns the Result, and attaches
+    # it to the message, because `deliver_now` hands the caller back the
+    # `Mail::Message` and not this return value.
+    def deliver!(mail)
+      payload, warnings = MessageMapper.new(@defaults).call(mail)
+      warnings.each { |warning| report(warning) }
+
+      body = @client.send_email(payload, idempotent: payload.key?(:idempotencyKey))
+      result = Result.new(body, mapping_warnings: warnings)
+      mail.instance_variable_set(:@posthaste_result, result)
+      result
+    end
+
+    # `settings` is exposed by ActionMailer as `posthaste_settings`, which means
+    # the key is reachable from `Rails.application.config` whatever this gem
+    # does. What this gem can control is that IT never prints it — and the
+    # default `#inspect` prints every instance variable, which is how a key
+    # reaches an error reporter without anybody having logged it.
+    def inspect
+      "#<Posthaste::DeliveryMethod api_key=#{Redaction.describe_key(@api_key).inspect} " \
+        "client=#{@client.inspect}>"
+    end
+    alias to_s inspect
+
+    private
+
+    def report(warning)
+      @on_warning&.call(warning)
+      # `warn` on a Logger is deprecated in neither Rails nor Ruby; a warning
+      # here is a mapping change the application should know about but that
+      # does not stop the send.
+      @logger&.warn("[posthaste] #{warning}")
+    end
+
+    def normalize(settings)
+      return {} if settings.nil?
+
+      settings.to_h.each_with_object({}) { |(k, v), out| out[k.to_sym] = v }
+    end
+  end
+end