Groundmail with Rails

The groundmail gem includes an Action Mailer delivery method. Your mailers, views and deliver_later calls stay the same; delivery goes through the Groundmail HTTP API. It works with Rails 6.1 and later.

1. Install

bundle add groundmail

export GROUNDMAIL_API_KEY=gm_your_key_here

2. Use the delivery method

With Rails loaded, the gem registers :groundmail as a delivery method.

# config/environments/production.rb
config.action_mailer.delivery_method = :groundmail

The API key is read from GROUNDMAIL_API_KEY. To set it explicitly, for example from credentials:

config.action_mailer.groundmail_settings = {
  api_key: Rails.application.credentials.dig(:groundmail, :api_key)
  # base_url: "https://api.groundmail.dev"
}

3. Send

class ReceiptMailer < ApplicationMailer
  default from: "Acme <receipts@yourdomain.com>"

  def receipt(order)
    @order = order
    attachments["receipt.pdf"] = order.receipt_pdf
    mail(to: order.email, subject: "Your receipt")
  end
end

ReceiptMailer.receipt(order).deliver_later

The From address must be on a domain you have verified in Groundmail. After delivery, message.message_id is the Groundmail email id.

Groundmail headers

mail(
  to: user.email,
  subject: "Welcome",
  "X-Groundmail-Tag" => "flow=signup",
  "X-Groundmail-Idempotency-Key" => "welcome-#{user.id}"
)

Header	Purpose
`X-Groundmail-Tag`	`name=value` tag (repeatable)
`X-Groundmail-Idempotency-Key`	Send once, even when your code retries
`X-Groundmail-Scheduled-At`	ISO 8601 time to send later

Without Rails

The same gem works in Sinatra, Hanami, Sidekiq jobs and plain Ruby. See the Ruby SDK.

Source

Groundmail/groundmail-sdks