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

Le package `billionsend` est le client BillionSend pour Elixir. Il 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-elixir](https://github.com/billionsend/billionsend-elixir).

## Installer

Nécessite Elixir 1.18 ou plus récent et OTP 25 ou plus récent. Le package n'a aucune dépendance : il utilise `:httpc` et `:ssl` d'OTP, ainsi que le module `JSON` intégré à Elixir.

```elixir
def deps do
  [{:billionsend, "~> 0.1"}]
end
```

## Envoyer un e-mail

```elixir
client = BillionSend.client()  # reads BILLIONSEND_API_KEY

{:ok, sent} =
  BillionSend.Emails.send(
    client,
    %{
      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"
  )

IO.puts(sent["id"])
```

`BillionSend.client(api_key: "bs_...")` prend la clé directement ; `base_url:`, `timeout:` (millisecondes par tentative, `60_000` par défaut), `max_retries:`, `default_headers:` et `transport:` (un `{module, state}` qui implémente `BillionSend.Transport`, pour envoyer par votre propre couche HTTP) règlent le reste. `BILLIONSEND_BASE_URL` remplace l'URL de l'API. Un client est une simple struct : construisez-le une seule fois et passez-le à chaque appel, depuis n'importe quel processus.

## Noms des fonctions

Chaque opération est une fonction qui porte le nom de son identifiant dans la [référence de l'API](/docs/fr/api-reference) : les groupes du chemin séparé par des points forment le module et le dernier segment la fonction, le camelCase étant écrit en snake_case. `emails.send` devient `BillionSend.Emails.send/3`, `emails.receiving.attachments.list` devient `BillionSend.Emails.Receiving.Attachments.list/3`, et `agent.claimEmail` devient `BillionSend.Agent.claim_email/2`. `emails.metrics` devient `BillionSend.Emails.metrics/2`, à côté de `BillionSend.Emails.Metrics.links/2`, `.countries/2` et `.clients/2`.

Une fonction prend le client, les paramètres de chemin dans l'ordre, le corps de la requête sous forme de map, puis une liste de mots-clés d'options : les paramètres de requête et d'en-tête (`BillionSend.Emails.list(client, limit: 50)` ; un paramètre de type liste accepte une liste), `:extra_headers` et `:timeout`, et, pour les fonctions d'envoi, `:idempotency_key`. Un corps que l'opération n'exige pas peut être omis. Une option inconnue, ou une option obligatoire manquante, lève une `ArgumentError` avant tout envoi. Chaque fonction renvoie `{:ok, answer}` ou `{:error, error}`, et sa jumelle en `!` (`BillionSend.Emails.send!/3`) renvoie la réponse ou lève une exception. Les réponses sont le JSON de l'API décodé en maps à 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. `BillionSend.Client.request(client, "GET", "/path", query: [...])` atteint tout ce que les fonctions ne couvrent pas.

## Idempotence et nouvelles tentatives

Les huit fonctions d'envoi (`Emails.send`, `Emails.batch`, `Emails.Receiving.reply` et `.forward`, `Inboxes.send`, `Inboxes.Drafts.send`, `Inboxes.Threads.Emails.reply` et `.forward`) envoient toujours un `Idempotency-Key`. Sans `idempotency_key:`, chaque appel en génère une (un UUID) que ses nouvelles tentatives réutilisent : une nouvelle tentative après une connexion coupée n'envoie donc jamais deux fois ; votre propre clé rend aussi sûre une répétition venue d'un autre processus. La même clé avec une requête différente est refusée par une `BillionSend.ConflictError`.

Les échecs qui méritent une nouvelle tentative sont retentés deux fois par défaut : 429, 5xx, aucune réponse (échec de connexion, délai dépassé), 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 une clé d'idempotence, comme chaque envoi. Le client attend ce que demande `Retry-After` et renvoie l'erreur immédiatement lorsqu'il demande plus d'une minute ; sinon il espace les tentatives de façon exponentielle, de 0,5 s à 8 s, avec de la gigue. `max_retries:` se règle sur le client (`0` désactive les nouvelles tentatives), et le processus appelant dort entre les tentatives.

## Erreurs

Un appel qui échoue renvoie `{:error, error}` avec une struct d'exception : `BillionSend.ValidationError` (400, 422), `AuthenticationError` (401, ou aucune clé configurée, avec `name` valant `missing_api_key` avant tout envoi), `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). `BillionSend.Error` correspond à tout autre statut. Chacune porte `status_code` (`nil` en l'absence de réponse), `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. `BillionSend.Errors.error?/1` distingue chacune d'elles des autres termes.

```elixir
case BillionSend.Emails.get(client, id) do
  {:ok, email} -> email["subject"]
  {:error, %BillionSend.NotFoundError{}} -> nil
  {:error, %BillionSend.RateLimitError{retry_after: seconds}} -> {:retry_in, seconds}
  {:error, error} -> Logger.error("#{error.status_code} #{error.name}: #{error.message} (request #{error.request_id})")
end
```

## Listes

Les fonctions de liste renvoient une page. Chaque liste à curseur a aussi une fonction `_all` (`search_all` pour la recherche de fils) qui renvoie un `Stream` paresseux, allant chercher les pages suivantes au fur et à mesure, en remontant lorsque `:before` est défini :

```elixir
client
|> BillionSend.Contacts.list_all(limit: 100)
|> Enum.each(&IO.puts(&1["email"]))
```

## 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 :

```elixir
alias BillionSend.{Inboxes, InboxStreamEvent}

{:ok, events} = Inboxes.Events.stream_inbox(client, "support@acme.dev", types: "inbox.email.received")

events
|> Stream.filter(&match?(%InboxStreamEvent{}, &1))  # a StreamGapEvent: events may be missing, read the threads again
|> Enum.each(fn %InboxStreamEvent{data: %{"inbox_id" => inbox_id, "data" => data}} ->
  %{"thread_id" => thread_id, "email_id" => email_id} = data

  Inboxes.Threads.Emails.reply(
    client,
    inbox_id,
    thread_id,
    email_id,
    %{text: "Thanks, we are on it."},
    idempotency_key: "reply/#{email_id}"
  )
end)
```

`stream_inbox/3` ouvre le flux d'abord, de sorte qu'un flux refusé (une clé révoquée, une clé limitée à une boîte qui demande le flux de l'équipe) donne aussitôt un `{:error, error}` ; ce qu'elle renvoie est un `Enumerable` paresseux de structs `BillionSend.InboxStreamEvent` (`id`, `event` comme `"inbox.email.received"`, et `data`, les champs `"type"`, `"created_at"`, `"inbox_id"` et `"data"` de la charge utile du webhook) et de structs `BillionSend.StreamGapEvent`. Le flux se reconnecte avec `Last-Event-ID` lorsque la connexion tombe et rejoue ce qu'il a manqué ; gardez l'`id` du dernier événement traité et repassez-le comme `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) règle la reconnexion, qui attend une seconde, ou ce que demande le champ `retry` du serveur, avant chaque tentative ; au-delà, l'énumération lève l'erreur de l'API pour la dernière tentative, ou `BillionSend.APIConnectionError` lorsqu'elle n'a reçu aucune réponse. Le flux d'une boîte de réception se termine une fois cette boîte supprimée ou expirée ; `BillionSend.Inboxes.Events.stream/2` suit toutes les boîtes que la clé peut lire. Énumérez un flux une seule fois, dans le processus qui l'a ouvert : interrompre l'énumération (`Enum.take/2`, `Stream.take_while/2`) ferme la connexion.

## Vérifier les webhooks

`BillionSend.verify_webhook/4` contrôle la signature et l'horodatage d'une livraison de [webhook](/docs/fr/concepts/webhooks) avec le secret `whsec_` du endpoint et renvoie `{:ok, event}` avec l'événement analysé, ou `{:error, %BillionSend.WebhookVerificationError{}}`. Passez le corps exactement tel qu'il est arrivé, avant tout parsing JSON ; les en-têtes peuvent être une map ou une liste de paires comme `conn.req_headers`, avec des noms dans n'importe quelle casse :

```elixir
# Phoenix: keep the raw body (a Plug.Parsers :body_reader that stores it in conn.assigns)
def create(conn, _params) do
  case BillionSend.verify_webhook(conn.assigns.raw_body, conn.req_headers, webhook_secret()) do
    {:ok, %{"type" => "email.bounced", "data" => %{"email_id" => id}}} ->
      mark_bounced(id)
      send_resp(conn, 204, "")

    {:ok, _event} ->
      send_resp(conn, 204, "")

    {:error, %BillionSend.WebhookVerificationError{}} ->
      send_resp(conn, 400, "")
  end
end
```

Une livraison de plus de cinq minutes est refusée (`tolerance:`, en secondes, permet de le changer), et pendant la rotation d'un secret, l'un ou l'autre secret est accepté. `verify_webhook!/4` renvoie l'événement ou lève une exception ; un secret qui n'est pas un secret `whsec_` lève une `ArgumentError`.
