Ruby

The Ruby SDK (Ruby 3.3+) is the coss gem. For Action Mailer, use the Rails driver instead: it sends your mailers' messages unchanged.

bundle add coss

require "coss"

client = Coss::Client.new # reads COSS_API_KEY

email = client.email.send_(
  from: "Acme <hello@acme.com>",
  to: ["ada@example.com"],
  subject: "Welcome to Acme",
  html: "<p>Thanks for signing up!</p>"
)
puts email.id, email.status

Arguments are keywords named like the API's fields (reply_to:, scheduled_at:). Sending is send_: send is a method of every Ruby object.

Options

Every method also takes request_options:, e.g. request_options: { max_retries: 0, timeout_in_seconds: 5 }.

Errors

A failed request raises a Coss::Errors::ResponseError subclass named after its status (Coss::Errors::NotFoundError, UnprocessableEntityError, TooManyRequestsError, …; client errors are ClientErrors, 5xx ServerErrors). code is the HTTP status and the message is the API's error envelope:

begin
  client.email.get(id: "email_01k7c8m4q2f3e9v6t5r1n0p8yz")
rescue Coss::Errors::NotFoundError => e
  error = JSON.parse(e.message)["error"]
  puts e.code, error["code"], error["request_id"]
end

Idempotency and lists

Methods whose endpoint takes an Idempotency-Key accept idempotency_key:; every other POST gets a random key of its own, reused by its retries.

List methods return one page. Pass the last id as after: while has_more is true:

page = client.email.list(limit: 100)
loop do
  page.data.each { |email| puts email.id }
  break unless page.has_more

  page = client.email.list(limit: 100, after: page.data.last.id)
end

Webhooks

Coss::Webhooks.verify checks a webhook request's signature and age and returns the parsed event (a Hash); it raises Coss::WebhookVerificationError when you must reject the request. Pass the raw body exactly as received, and the headers as a Hash, a Rack env or Rails' request.headers. Coss::Webhooks.verify_log_drain_batch does the same for log drains and returns the batch's lines.

class CossWebhooksController < ActionController::API
  def create
    event = Coss::Webhooks.verify(request.raw_post, request.headers, ENV.fetch("COSS_WEBHOOK_SECRET"))
    Rails.logger.info(event["type"])
    head :no_content
  rescue Coss::WebhookVerificationError
    head :bad_request
  end
end