Skip to main content
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

That writes the gem into your Gemfile:
Then point ActionMailer at it:

Send

Your mailers keep the code they already have:
The delivery method maps the sender, recipients including blind copies, the subject, both bodies, attachments and your custom headers. Anything ActionMailer’s message can express passes through, with one exception: an inline 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 raises Mailkube::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:
For the detail, which error, which status, whether a retry is safe, read 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.
The 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:
Subscribers run inside the request, and the endpoint answers as soon as they return: enqueue anything slow, or delivery latency becomes retries. The endpoint answers 204 on success, 400 when verification fails, and 500 when no secret is configured. That last one keeps the platform retrying instead of discarding deliveries while your configuration is broken. CSRF is skipped on this controller; the signature authenticates the request and covers the exact bytes sent, so keep body-rewriting middleware off this path. The controller answers POST only, and mailkube activates an endpoint only after probing it with 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.