GroundmailDocs

Groundmail with Ruby

Use the Ruby SDK in Rails, Sinatra, Sidekiq jobs, or any server-side Ruby app where your API key can stay private.

1. Install the SDK

gem install groundmail

Or add to your Gemfile:

gem "groundmail", "~> 0.8"

2. Configure your API key

export GROUNDMAIL_API_KEY=gm_your_key_here

3. Send an email (API client)

require "groundmail"

tx = Groundmail::Client.new(ENV.fetch("GROUNDMAIL_API_KEY"))

result = tx.emails.send(
  from: "ops@yourdomain.com",
  to: "user@example.com",
  subject: "Your receipt",
  html: "<p>Thanks for your purchase.</p>"
)

puts result["id"], result["status"]

With Rails present, the gem registers a delivery method automatically.

# config/environments/production.rb (or application.rb)
config.action_mailer.delivery_method = :groundmail
config.action_mailer.groundmail_settings = {
  api_key: ENV.fetch("GROUNDMAIL_API_KEY")
  # base_url: "https://api.groundmail.dev"
}

Then send Mailables as usual:

UserMailer.welcome(user).deliver_later

Without the Railtie (manual registration):

ActionMailer::Base.add_delivery_method :groundmail, Groundmail::DeliveryMethod

Tags, idempotency, and schedule

Set headers on the message:

mail(
  to: user.email,
  subject: "Welcome",
  "X-Groundmail-Tag" => "campaign=welcome",
  "X-Groundmail-Idempotency-Key" => "welcome-#{user.id}"
  # "X-Groundmail-Scheduled-At" => "2030-01-01T00:00:00Z"
)

X-Groundmail-Tag uses name=value. Custom non-reserved headers are forwarded to the API headers field.

Resources

The client includes thin wrappers for common API resources:

  • tx.emails — send, batch, list, cancel, resend, test webhooks, deliverability insights
  • tx.domains — create, verify, apply DNS, update, delete
  • tx.webhooks — CRUD for webhook endpoints
  • tx.templates — CRUD plus publish
  • tx.suppressions — list, create, remove

See the API reference for request fields. The Ruby SDK accepts the same JSON shapes as the REST API.

Source

Package source lives in ruby/ in the public groundmail-sdks repository.