---
title: Ruby-SDK
description: "E-Mails senden, ein Postfach bedienen und Webhooks verifizieren mit dem Gem billionsend: jede API-Operation, Wiederholungsversuche und Idempotenzschlüssel."
ai:
  exclude: true
---

Das Gem `billionsend` ist der BillionSend-Client für Ruby. Es deckt jede Operation der [API-Referenz](/docs/de/api-reference) ab: Versand, Domains, Kontakte, Newsletter-Versand, Vorlagen, Webhooks, Postfächer mit ihren Threads und Entwürfen, Live-Ereignisse von Postfächern und die Agent-Registrierung. Der Quellcode liegt auf GitHub unter [billionsend/billionsend-ruby](https://github.com/billionsend/billionsend-ruby).

## Installation

Erfordert Ruby 3.1 oder neuer. Das Gem hat keine Laufzeit-Abhängigkeiten: Es nutzt `net/http`, `json` und `openssl` aus der Standardbibliothek.

```sh
gem install billionsend
```

In einem Gemfile: `gem "billionsend"`.

## E-Mail senden

```ruby
require "billionsend"

client = BillionSend::Client.new # liest BILLIONSEND_API_KEY

sent = client.emails.send({
  from: "Acme <hello@acme.dev>",
  to: ["success@simulator.amazonses.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_...")` nimmt den Schlüssel direkt entgegen. `base_url:`, `timeout:` (Sekunden pro Versuch, Standard 60), `max_retries:`, `default_headers:` und `transport:` (alles, was auf `call` und `open_stream` antwortet wie `BillionSend::NetHTTPTransport`, um über Ihren eigenen HTTP-Stack zu senden) legen den Rest fest. `BILLIONSEND_BASE_URL` überschreibt die API-URL.

## Methodennamen

Jede Operation ist eine Methode, benannt nach ihrer ID in der [API-Referenz](/docs/de/api-reference), der durch Punkte getrennte Pfad als Kette von Ressourcen in snake_case: `emails.send` ist `client.emails.send`, `emails.receiving.attachments.list` ist `client.emails.receiving.attachments.list`, und `agent.claimEmail` ist `client.agent.claim_email`. `emails.metrics` ist `client.emails.metrics.call`, neben `.links`, `.countries` und `.clients`.

Eine Methode nimmt die Pfadparameter der Reihe nach, den Request-Body als Hash in geschweiften Klammern, dann die Query- und Header-Parameter als Schlüsselwortargumente und zuletzt `extra_headers:` und `timeout:`. Bodies nehmen Symbole oder Strings als Schlüssel an. Antworten sind Hashes mit String-Schlüsseln und den Feldnamen der API (`sent["id"]`), sodass die API-Referenz sie Feld für Feld beschreibt. `emails`, `inboxes` und `broadcasts` haben eine Methode `send`, die `Object#send` bei ihnen verdeckt: Rufen Sie ihre Methoden dynamisch mit `public_send` auf.

## Idempotenz und Wiederholungsversuche

Die acht Versand-Operationen (`emails.send`, `emails.batch`, Antworten und Weiterleitungen auf empfangene Mails, `inboxes.send`, `inboxes.drafts.send`, Thread-Antworten und -Weiterleitungen) senden immer einen `Idempotency-Key`. Ohne `idempotency_key:` denkt sich jeder Aufruf einen aus, den seine Wiederholungen weiterverwenden. Ein erneuter Versuch nach einem Timeout sendet also nie doppelt, und Ihr eigener Schlüssel macht auch eine Wiederholung aus einem anderen Prozess sicher.

Fehlschläge, bei denen sich ein neuer Versuch lohnt, werden standardmäßig zweimal wiederholt: 429, 5xx, Timeouts, Netzwerkfehler und das `409 concurrent_idempotent_requests`, das antwortet, solange der erste Versuch mit demselben Schlüssel noch läuft. Wiederholt werden nur Anfragen, die sich gefahrlos wiederholen lassen: `GET`, `PUT`, `DELETE` und jede Anfrage mit einem `Idempotency-Key`, wie ihn jede Versand-Operation trägt. Der Client wartet so lange, wie `Retry-After` es verlangt, und löst sofort einen Fehler aus, wenn es mehr als eine Minute verlangt. Sonst weicht er exponentiell von 0,5 s bis 8 s zurück, bis zu einem Viertel kürzer nach Zufall. Jede Methode nimmt `timeout:` und `extra_headers:` für diesen Aufruf entgegen, die Versand-Methoden zusätzlich `idempotency_key:`. `max_retries:` wird am Client gesetzt.

## Fehler

Ein fehlgeschlagener Aufruf löst `ValidationError` (400, 422), `AuthenticationError` (401 oder kein Schlüssel konfiguriert), `PermissionDeniedError` (403), `NotFoundError` (404), `ConflictError` (409), `RateLimitError` (429, mit `retry_after` in Sekunden), `APIError` (5xx), `APIConnectionError` (keine Antwort) oder `APITimeoutError` (der Versuch hat das Zeitlimit überschritten, eine Art von `APIConnectionError`) aus. Alle liegen im Modul `BillionSend` und erweitern `BillionSend::Error`, das für jeden anderen Status selbst ausgelöst wird, mit `status_code`, `name` (dem Fehlernamen der API), `message` und `request_id`, dem `x-request-id` der Antwort, der zugleich die ID der Anfrage auf der Logs-Seite des Dashboards ist.

```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
```

## Listen

Listen-Methoden liefern eine Seite. Jede Cursor-Liste hat außerdem eine Methode `..._all` (`search_all` für die Thread-Suche), die einen trägen `Enumerator` liefert und die nächsten Seiten nach und nach abruft, rückwärts, wenn `before:` gesetzt ist:

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

## Das Postfach eines Agenten

Warten Sie im [Ereignis-Stream](/docs/de/inboxes) auf neue Mails und antworten Sie in ihrem 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) # Ereignisse können fehlen: Threads erneut lesen

    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
```

Der Stream verbindet sich mit `Last-Event-ID` neu, wenn die Verbindung abbricht, und spielt Verpasstes nach. Behalten Sie `stream.last_event_id` und übergeben Sie es als `last_event_id:` zurück, um nach einem Neustart fortzusetzen. Ein `StreamGapEvent` kommt einmal, wenn der Stream von weiter als 24 Stunden zurück fortgesetzt wird. `max_reconnects:` (Standard 5 fehlgeschlagene Wiederverbindungen in Folge, `0` gibt beim ersten auf) steuert das Wiederverbinden, das vor jedem Versuch eine Sekunde wartet oder so lange, wie das Feld `retry` des Servers verlangt. Der Stream eines Postfachs endet, nachdem dieses Postfach gelöscht wurde oder abgelaufen ist. `client.inboxes.events.stream` folgt jedem Postfach, das der Schlüssel lesen kann.

## Webhooks verifizieren

`BillionSend.verify_webhook` prüft Signatur und Zeitstempel einer [Webhook](/docs/de/concepts/webhooks)-Zustellung mit dem `whsec_`-Secret des Endpunkts und liefert das geparste Ereignis. Übergeben Sie den Body genau so, wie er angekommen ist. Header-Namen passen unabhängig von der Groß- und Kleinschreibung:

```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
```

Eine Zustellung, die älter als fünf Minuten ist, wird abgelehnt, und während einer Rotation des Secrets verifiziert jedes der beiden Secrets.

## Agent-Registrierung

```ruby
signup = BillionSend::Client.new.agent.signup({ human_email: "owner@acme.dev", name: "Support agent" })
puts signup["inbox"]["email_address"]
```

Der Aufruf braucht keinen API-Schlüssel. Die Antwort enthält den neuen Schlüssel und das Postfach. Was ein nicht übernommenes Konto darf, steht unter [Agent-Registrierung](/docs/de/agent-signup).
