mailkube-rails registers the :mailkube ActionMailer delivery method, so mailers, deliver_now, deliver_later, attachments and ActionMailer::Base.deliveries in tests all keep working while delivery goes through mailkube. It is a thin adapter over the Ruby SDK, which owns the API surface, the errors and the signature verification. Requires Ruby 3.4+ and Rails 7.2.3+.
Install
Gemfile:
Send
Your mailers keep the code they already have:cid: image arrives as an ordinary attachment, because the API’s attachment model carries no content id.
Tags, topics, templates, scheduling and idempotency keys have no slot in Mail::Message. Reach them through the SDK directly, which reads the same MAILKUBE_API_KEY:
Reading the accepted send back
Mail::Message#deliver! returns the delivery method’s response when return_response is set, which is how the ActionMailer path can still hand you the ids:
deliver_later and deliver_now are unaffected; they return what they always did.
Configure
Two homes, and they do not overlap:
An unset setting is omitted rather than passed as nil, and the SDK’s own environment resolution still applies. The key can come from
MAILKUBE_API_KEY alone, with no Rails configuration at all.
ActionMailer resolves the delivery method per message, so overriding the settings on one mailer gives it its own client:
Handle failures
A failed delivery raisesMailkube::Rails::DeliveryError with the SDK’s exception preserved as cause. The class this gem owns is the one you name in a retry policy, so a reorganization of the SDK’s hierarchy can never break it:
cause:
config.action_mailer.raise_delivery_errors = false still swallows failures exactly as it does for any other delivery method.
Receiving webhooks
You write the route: a mountable engine would force a path on your application for one endpoint, so the gem ships the controller and lets you mount it where you want.require is needed and the .action(:create) form is deliberate. A gem’s lib/ is on the load path but is not an autoload path, so the "controller#action" string form would name a constant Zeitwerk has never been told about.
Deliveries are verified against the raw request body and published as one notification. An event type this gem’s SDK release does not model still reaches your subscriber with its payload intact:
GET <url>?hub.mode=subscribe&hub.challenge=<token> and reading the token back. Add the probe as a GET route on the same path:
Next steps
Ruby SDK
The gem underneath: keyword arguments, scheduled sends, typed events, and RBS signatures.
Webhooks
Every event the notification can carry, the signing scheme, and delivery retries.