CamelMailer
DocsAPISDKsTemplatesHow-to

Ruby & Rails SDK

The official camelmailer gem is a plain Ruby client plus a :camelmailer ActionMailer delivery method, so your existing mailers send through CamelMailer. No runtime dependencies, Ruby 3.1+.

Install

terminal
gem install camelmailer
# or in your Gemfile
gem "camelmailer"

Quickstart

mailer.rb
require "camelmailer"

CamelMailer.configure { |c| c.api_key = "cm_..." }

CamelMailer::Emails.send(
  from: "billing@acme.com",
  to: ["ada@example.com"],
  subject: "Your receipt",
  html_body: "<h1>Thanks!</h1>"
)

Prefer no global state? CamelMailer::Client.new(api_key: …) exposes the same resources as client.emails.send(...).

Rails: the delivery method

The gem registers the :camelmailer ActionMailer delivery method automatically. Configure it and use ActionMailer as usual:

config/environments/production.rb
config.action_mailer.delivery_method = :camelmailer
config.action_mailer.camelmailer_settings = {
  api_key: Rails.application.credentials.dig(:camelmailer, :api_key),
  base_url: "https://mail.example.com" # optional, self-hosted only
}
app/mailers/receipt_mailer.rb
class ReceiptMailer < ApplicationMailer
  def receipt
    mail(
      from: "billing@acme.com",
      to: params[:to],
      subject: "Your receipt",
      tag: "receipt",         # CamelMailer tag (filtering & stats)
      stream: "transactional" # optional message stream
    )
  end
end

Send with a template

template.rb
CamelMailer::Emails.send_with_template(
  from: "hello@acme.com",
  to: ["ada@example.com"],
  template: "welcome",
  template_model: { name: "Ada" }
)

Error handling

API errors raise typed exceptions with code, message and status_code.

errors.rb
begin
  CamelMailer::Emails.send(from: "x@unverified.test", to: ["a@b.com"])
rescue CamelMailer::ValidationError => e
  e.code        # => "ValidationError"
  e.status_code # => 422
rescue CamelMailer::UnauthorizedError
  # bad API key
rescue CamelMailer::ConnectionError
  # network problem
rescue CamelMailer::Error => e
  # base class for everything above
end

Self-hosted instances

The base URL defaults to the cloud (https://app.camelmailer.com). Point it at your own instance:

self-hosted.rb
CamelMailer.configure do |c|
  c.api_key = "cm_..."
  c.base_url = "https://mail.example.com"
end
Full field reference: Messages API.

Links

GitHub repository · RubyGems package