---
title: Ruby SDK
description: Use BillionSend from Ruby with the billionsend gem.
---

The `billionsend` gem is the BillionSend client for Ruby. It covers every operation of the [API reference](/docs/api-reference): sending, domains, contacts, broadcasts, templates, webhooks, inboxes with their threads and drafts, live inbox events and agent sign-up. The source is [billionsend/billionsend-ruby](https://github.com/billionsend/billionsend-ruby) on GitHub.

## Install

Needs Ruby 3.1 or newer. The gem has no runtime dependencies: it uses `net/http`, `json` and `openssl` from the standard library.

```sh
gem install billionsend -v 0.1.0
```

In a Gemfile, `gem "billionsend", "~> 0.1"`.

## Send an email

```ruby
require "billionsend"

client = BillionSend::Client.new # reads BILLIONSEND_API_KEY

sent = client.emails.send({
  from: "Acme <hello@acme.dev>",
  to: ["ana@example.com"],
  subject: "Welcome to Acme",
  html: "<p>Glad you are here.</p>"
}, idempotency_key: "welcome/ana")

puts sent["id"]
```

`BillionSend::Client.new(api_key: "bs_...")` takes the key directly; `base_url:`, `timeout:` (seconds per attempt, default 60), `max_retries:`, `default_headers:` and `transport:` (anything that answers `call` and `open_stream` like `BillionSend::NetHTTPTransport`, to send through your own HTTP stack) set the rest. `BILLIONSEND_BASE_URL` overrides the API URL.

## Method names

Each operation is a method named after its id in the [API reference](/docs/api-reference), the dotted path as a chain of resources in snake_case: `emails.send` is `client.emails.send`, `emails.receiving.attachments.list` is `client.emails.receiving.attachments.list`, and `agent.claimEmail` is `client.agent.claim_email`. `emails.metrics` is `client.emails.metrics.call`, beside `.links`, `.countries` and `.clients`.

A method takes the path parameters in order, the request body as a Hash in braces, then the query and header parameters as keyword arguments, and last `extra_headers:` and `timeout:`. Bodies take symbol or string keys; answers are Hashes with string keys and the API's own field names (`sent["id"]`), so the API reference describes them field for field. `emails`, `inboxes` and `broadcasts` have a `send` method, which hides `Object#send` on them: reach their methods dynamically with `public_send`.

## Idempotency and retries

The eight sending operations (`emails.send`, `emails.batch`, received-mail replies and forwards, `inboxes.send`, `inboxes.drafts.send`, thread replies and forwards) always send an `Idempotency-Key`. Without `idempotency_key:`, each call makes one up that its retries reuse, so a retry after a timeout never sends twice; your own key also makes a repeat from another process safe.

Failures worth retrying are retried twice by default: 429, 5xx, timeouts, network errors, and the `409 concurrent_idempotent_requests` answered while the first attempt with the same key is still running. Only requests safe to repeat are retried: `GET`, `PUT`, `DELETE` and any request carrying an `Idempotency-Key`, as every sending operation does. The client waits as `Retry-After` asks, and raises at once when it asks for more than a minute; otherwise it backs off exponentially from 0.5 s to 8 s, less up to a quarter at random. Every method takes `timeout:` and `extra_headers:` for that call, and the sending ones `idempotency_key:`; `max_retries:` is set on the client.

## Errors

A failed call raises `ValidationError` (400, 422), `AuthenticationError` (401, or no key configured), `PermissionDeniedError` (403), `NotFoundError` (404), `ConflictError` (409), `RateLimitError` (429, with `retry_after` in seconds), `APIError` (5xx), `APIConnectionError` (no answer) or `APITimeoutError` (the attempt timed out, a kind of `APIConnectionError`). All are in the `BillionSend` module and extend `BillionSend::Error`, raised as itself for any other status, with `status_code`, `name` (the API's error name), `message` and `request_id`, the answer's `x-request-id`, which is the request's id on the dashboard's Logs page.

```ruby
begin
  puts client.emails.get(id)["subject"]
rescue BillionSend::NotFoundError
  # no such email
rescue BillionSend::Error => e
  warn "#{e.status_code} #{e.name}: #{e.message} (request #{e.request_id})"
end
```

## Lists

List methods return one page. Every cursor list also has a `..._all` method (`search_all` for thread search) that returns a lazy `Enumerator`, fetching the next pages as it goes, backward when `before:` is set:

```ruby
client.contacts.list_all(limit: 100).each do |contact|
  puts contact["email"]
end
```

## An agent's inbox

Wait for new mail on the [event stream](/docs/inboxes) and reply in its thread:

```ruby
stream = client.inboxes.events.stream_inbox("support@acme.dev", types: "inbox.email.received")
begin
  stream.each do |event|
    next if event.is_a?(BillionSend::StreamGapEvent) # events may be missing: read the threads again

    data = event.data["data"]
    client.inboxes.threads.emails.reply(
      event.data["inbox_id"], data["thread_id"], data["email_id"],
      { text: "Thanks, we are on it." },
      idempotency_key: "reply/#{data["email_id"]}"
    )
  end
ensure
  stream.close
end
```

The stream reconnects with `Last-Event-ID` when the connection drops and replays what it missed; keep `stream.last_event_id` and pass it back as `last_event_id:` to resume after a restart. A `StreamGapEvent` comes once when the stream resumes from more than 24 hours back. `max_reconnects:` (default 5 failed reconnects in a row; `0` gives up at the first) tunes reconnecting, which waits a second, or what the server's `retry` field asks, before each attempt. One inbox's stream ends after that inbox is deleted or expires; `client.inboxes.events.stream` follows every inbox the key can read.

## Verify webhooks

`BillionSend.verify_webhook` checks a [webhook](/docs/concepts/webhooks) delivery's signature and timestamp with the endpoint's `whsec_` secret and returns the parsed event. Pass the body exactly as it arrived; header names match in any case:

```ruby
# config.ru
require "billionsend"

SECRET = ENV.fetch("BILLIONSEND_WEBHOOK_SECRET")
NAMES = %w[webhook-id webhook-timestamp webhook-signature].freeze

app = lambda do |env|
  headers = NAMES.to_h { |name| [name, env["HTTP_#{name.upcase.tr("-", "_")}"]] }
  event = BillionSend.verify_webhook(env["rack.input"].read, headers, SECRET)
  warn event["type"]
  [204, {}, []]
rescue BillionSend::WebhookVerificationError
  [400, {}, ["bad signature"]]
end

run app
```

A delivery older than five minutes is refused, and during a secret rotation either secret verifies.
