Rails and ActionMailer

The whole change

# config/environments/production.rb
config.action_mailer.delivery_method = :smtp
config.action_mailer.smtp_settings = {
  address: 'smtp.sendgrid.net',
  port: 587,
  user_name: 'apikey',
  password: ENV['SENDGRID_KEY'],
}

# …and every mailer in app/mailers, elsewhere.

posthaste-rails registers a delivery method through ActionMailer’s own add_delivery_method. Its only dependency is ActionMailer itself — the HTTP is Net::HTTP and the JSON is the standard library — so it adds nothing to your lockfile that Rails was not already carrying. Ruby 3.1 or newer, ActionMailer 6.1 or newer.

The from address must be on one of your verified domains, exactly as it must for a direct API send. Nothing else about your mailers changes:

class InvoiceMailer < ApplicationMailer
  def issued(invoice)
    @invoice = invoice
    attachments['invoice.pdf'] = invoice.to_pdf
    mail(
      to: invoice.customer.email,
      cc: invoice.accountant_email,
      reply_to: 'Acme Billing <[email protected]>',
      subject: "Invoice #{invoice.number}",
    )
  end
end

InvoiceMailer.issued(invoice).deliver_now

When to use this instead of the SMTP relay

Posthaste already runs an SMTP relay, and ActionMailer can point at it today with no gem at all. That is a perfectly good answer, and for a long-running server on a network that allows outbound SMTP it is often the simpler one — so here is the honest comparison rather than a pitch.

Reading the result

deliver_now hands back the Mail::Message, as it always has. The API’s answer is attached to it.

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  # [{ 'to' => …, 'reason' => 'complaint' }]
mail.posthaste_result.warnings    # the platform's pre-send lint findings
mail.posthaste_result.mapping_warnings # what the gem had to change

#posthaste_result is the only method the gem adds to a class it does not own, and it returns nil for a message delivered any other way. The duplicate? flag is read from the response body rather than from a 200 versus a 202, because the body is the authoritative answer and survives a proxy that normalises the status — and an application that bills or counts per send has to be able to tell an idempotency replay from a new message.

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.

def issued(invoice)
  mail(
    to: invoice.customer.email,
    subject: "Invoice #{invoice.number}",

    # Everything the API offers that ActionMailer has no word for.
    '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}",
    'X-Posthaste-Scheduled-At' => '2026-09-01T09:00:00Z',
  )
end

mail(
  to: invoice.customer.email,
  subject: "Invoice #{invoice.number}",
  # No view is sent: the stored template supplies both parts.
  'X-Posthaste-Template' => 'invoice-issued',
  'X-Posthaste-Variables' => { name: 'Ada', amount: '£42.00' }.to_json,
)

What maps, what changes, what is refused

ActionMailer hands a delivery method a fully-composed Mail::Message, which is 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. So anything that cannot be honoured is either a warning you can see or a synchronous error naming the field, never a quiet omission.

Mapped, unchanged

Mapped, with something changed

Each of these produces a mapping warning: it appears on mail.posthaste_result.mapping_warnings and is passed to the on_warning hook, so you find out on the first send rather than in a support ticket.

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. Posthaste composes the MIME and signs the identity headers itself, and 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.

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, so each of them is its own class and each of them arrives out of deliver_now.

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.
  InvoiceMailJob.set(wait: e.retry_after_seconds).perform_later(invoice)

rescue Posthaste::RateLimited => e
  # Transient, and it clears on its own.
  InvoiceMailJob.set(wait: e.retry_after_seconds || 60).perform_later(invoice)

rescue Posthaste::ContentBlockedError => e
  # The whole lint report, warnings included, so one pass fixes everything.
  Rails.logger.error([e.check, e.findings].inspect)
end

Every class descends from Posthaste::Error, so one rescue catches the lot. Posthaste::UnprocessableError covers the 422s, which are permanent by construction — the same bytes get the same answer — and nothing under it is ever retried.

Branch on error.type, a stable machine-readable string, and never on the message. A type this gem 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.

config.action_mailer.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 on a job rather than blocking a web request for a quarter of an hour.

Settings

Everything is optional except the key, which falls back to POSTHASTE_API_KEY. base_url is the whole story for a self-hosted install: point it at your own API host and the rest works unchanged.

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}") },
}

An unrecognised setting raises Posthaste::ConfigurationError naming it, rather than being ignored — a typo like api_kye: would otherwise fall back silently to the environment variable, or to no key at all.

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.

mailer.message.delivery_method.inspect
# => #<Posthaste::DeliveryMethod api_key="ph_live_***redacted***" …>

So every object in the gem defines its own #inspect, and every string built for a human goes through a redactor first. The ph_live_ prefix survives because it is not secret — it is printed beside every key in the dashboard — and it is enough to confirm that what was passed is a Posthaste key at all. 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 in two passes — this client’s own key, then anything key-shaped — which catches a different account’s key echoed back by a proxy that quoted the request line.

Your own mailer tests

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. Leave your test environment on :test and your development environment on :letter_opener if that is what it is on today.

To drive the gem itself without a network, pass a transport: in posthaste_settings — anything that responds to call(method, url, headers, body) and returns a Posthaste::Response.