---
title: SDK Ruby
description: "Envoyez des e-mails, gérez une boîte de réception, vérifiez des webhooks en Ruby avec la gem billionsend : toute l'API, nouvelles tentatives, idempotence."
ai:
  exclude: true
---

La gem `billionsend` est le client BillionSend pour Ruby. Elle couvre toutes les opérations de la [référence de l'API](/docs/fr/api-reference) : envoi, domaines, contacts, campagnes, templates, webhooks, boîtes de réception avec leurs fils de discussion et leurs brouillons, événements de boîte de réception en direct et inscription des agents. Le code source est sur GitHub : [billionsend/billionsend-ruby](https://github.com/billionsend/billionsend-ruby).

## Installer

Nécessite Ruby 3.1 ou plus récent. La gem n'a aucune dépendance d'exécution : elle utilise `net/http`, `json` et `openssl` de la bibliothèque standard.

```sh
gem install billionsend
```

Dans un Gemfile, `gem "billionsend"`.

## Envoyer un e-mail

```ruby
require "billionsend"

client = BillionSend::Client.new # reads 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_...")` prend la clé directement ; `base_url:`, `timeout:` (en secondes par tentative, 60 par défaut), `max_retries:`, `default_headers:` et `transport:` (tout objet qui répond à `call` et `open_stream` comme `BillionSend::NetHTTPTransport`, pour envoyer par votre propre pile HTTP) règlent le reste. `BILLIONSEND_BASE_URL` remplace l'URL de l'API.

## Noms des méthodes

Chaque opération est une méthode qui porte le nom de son identifiant dans la [référence de l'API](/docs/fr/api-reference), le chemin séparé par des points devenant une chaîne de ressources en snake_case : `emails.send` devient `client.emails.send`, `emails.receiving.attachments.list` devient `client.emails.receiving.attachments.list`, et `agent.claimEmail` devient `client.agent.claim_email`. `emails.metrics` devient `client.emails.metrics.call`, à côté de `.links`, `.countries` et `.clients`.

Une méthode prend, dans l'ordre, les paramètres de chemin, le corps de la requête sous forme de Hash entre accolades, puis les paramètres de requête et d'en-tête en arguments nommés, et enfin `extra_headers:` et `timeout:`. Les corps acceptent des clés symbole ou chaîne ; les réponses sont des Hash à clés chaîne avec les noms de champ de l'API elle-même (`sent["id"]`) : la référence de l'API les décrit donc champ par champ. `emails`, `inboxes` et `broadcasts` ont une méthode `send`, qui masque `Object#send` sur eux : appelez leurs méthodes de façon dynamique avec `public_send`.

## Idempotence et nouvelles tentatives

Les huit opérations d'envoi (`emails.send`, `emails.batch`, réponses et transferts d'e-mails reçus, `inboxes.send`, `inboxes.drafts.send`, réponses et transferts dans un fil) envoient toujours un `Idempotency-Key`. Sans `idempotency_key:`, chaque appel en génère une que ses nouvelles tentatives réutilisent : une nouvelle tentative après un délai dépassé n'envoie donc jamais deux fois. Votre propre clé rend aussi sûre une répétition venue d'un autre processus.

Les échecs qui méritent une nouvelle tentative sont retentés deux fois par défaut : 429, 5xx, délais dépassés, erreurs réseau, et le `409 concurrent_idempotent_requests` renvoyé tant que la première tentative avec la même clé est encore en cours. Seules les requêtes sans danger à répéter sont retentées : `GET`, `PUT`, `DELETE` et toute requête qui porte un `Idempotency-Key`, comme le fait chaque opération d'envoi. Le client attend ce que demande `Retry-After` et lève l'erreur aussitôt lorsqu'il demande plus d'une minute ; sinon il espace les tentatives de façon exponentielle, de 0,5 s à 8 s, diminuées au hasard d'un quart au plus. Chaque méthode accepte `timeout:` et `extra_headers:` pour cet appel, et celles d'envoi `idempotency_key:` ; `max_retries:` se règle sur le client.

## Erreurs

Un appel qui échoue lève `ValidationError` (400, 422), `AuthenticationError` (401, ou aucune clé configurée), `PermissionDeniedError` (403), `NotFoundError` (404), `ConflictError` (409), `RateLimitError` (429, avec `retry_after` en secondes), `APIError` (5xx), `APIConnectionError` (aucune réponse) ou `APITimeoutError` (la tentative a dépassé son délai, un cas particulier de `APIConnectionError`). Toutes se trouvent dans le module `BillionSend` et étendent `BillionSend::Error`, levée telle quelle pour tout autre statut, avec `status_code`, `name` (le nom de l'erreur dans l'API), `message` et `request_id`, le `x-request-id` de la réponse, qui est l'identifiant de la requête dans la page Journaux du tableau de bord.

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

## Listes

Les méthodes de liste renvoient une page. Chaque liste à curseur dispose aussi d'une méthode `..._all` (`search_all` pour la recherche de fils) qui renvoie un `Enumerator` paresseux et va chercher les pages suivantes au fur et à mesure, en remontant lorsque `before:` est défini :

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

## La boîte de réception d'un agent

Attendez les nouveaux e-mails sur le [flux d'événements](/docs/fr/inboxes) et répondez dans leur fil :

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

Le flux se reconnecte avec `Last-Event-ID` lorsque la connexion tombe et rejoue ce qu'il a manqué. Gardez `stream.last_event_id` et repassez-le dans `last_event_id:` pour reprendre après un redémarrage. Un `StreamGapEvent` arrive une seule fois lorsque le flux reprend depuis plus de 24 heures en arrière. `max_reconnects:` (5 reconnexions ratées d'affilée par défaut ; `0` abandonne dès la première) règle la reconnexion, qui attend une seconde, ou ce que demande le champ `retry` du serveur, avant chaque tentative. Le flux d'une boîte de réception se termine une fois cette boîte supprimée ou expirée ; `client.inboxes.events.stream` suit toutes les boîtes que la clé peut lire.

## Vérifier les webhooks

`BillionSend.verify_webhook` contrôle la signature et l'horodatage d'une livraison de [webhook](/docs/fr/concepts/webhooks) avec le secret `whsec_` du endpoint, puis renvoie l'événement analysé. Passez le corps exactement tel qu'il est arrivé ; les noms d'en-tête sont reconnus quelle que soit la casse :

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

Une livraison de plus de cinq minutes est refusée, et pendant la rotation d'un secret, l'un ou l'autre secret est accepté.

## Inscription d'un agent

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

L'appel n'a pas besoin de clé API ; la réponse contient la nouvelle clé et la boîte de réception. Voir [Inscription d'un agent](/docs/fr/agent-signup) pour ce qu'un compte non réclamé peut faire.
