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

Das Hex-Paket `billionsend` ist der BillionSend-Client für Elixir. 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-elixir](https://github.com/billionsend/billionsend-elixir).

## Installation

Erfordert Elixir 1.18 oder neuer und OTP 25 oder neuer. Das Paket hat keine Abhängigkeiten: Es nutzt `:httpc` und `:ssl` aus OTP und das in Elixir eingebaute `JSON`.

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

## E-Mail senden

```elixir
client = BillionSend.client()  # liest 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_...")` nimmt den Schlüssel direkt entgegen. `base_url:`, `timeout:` (Millisekunden pro Versuch, Standard `60_000`), `max_retries:`, `default_headers:` und `transport:` (ein `{module, state}`, das `BillionSend.Transport` implementiert, um über Ihre eigene HTTP-Schicht zu senden) legen den Rest fest. `BILLIONSEND_BASE_URL` überschreibt die API-URL. Ein Client ist eine schlichte Struct: Erzeugen Sie ihn einmal und übergeben Sie ihn an jeden Aufruf, aus jedem Prozess.

## Funktionsnamen

Jede Operation ist eine Funktion, benannt nach ihrer ID in der [API-Referenz](/docs/de/api-reference): Die Gruppen des durch Punkte getrennten Pfads bilden das Modul und das letzte Segment die Funktion, camelCase in snake_case geschrieben. `emails.send` ist `BillionSend.Emails.send/3`, `emails.receiving.attachments.list` ist `BillionSend.Emails.Receiving.Attachments.list/3`, und `agent.claimEmail` ist `BillionSend.Agent.claim_email/2`. `emails.metrics` ist `BillionSend.Emails.metrics/2`, neben `BillionSend.Emails.Metrics.links/2`, `.countries/2` und `.clients/2`.

Eine Funktion nimmt den Client, die Pfadparameter der Reihe nach, den Request-Body als Map und dann eine Keyword-Liste mit Optionen: die Query- und Header-Parameter (`BillionSend.Emails.list(client, limit: 50)`; ein Listenparameter nimmt eine Liste), `:extra_headers` und `:timeout`, bei den Versand-Funktionen außerdem `:idempotency_key`. Ein Body, den die Operation nicht verlangt, darf entfallen. Eine unbekannte Option oder eine fehlende Pflichtoption löst `ArgumentError` aus, bevor etwas gesendet wird. Jede Funktion liefert `{:ok, answer}` oder `{:error, error}`, und ihr Gegenstück mit `!` (`BillionSend.Emails.send!/3`) liefert die Antwort oder löst einen Fehler aus. Antworten sind das JSON der API, dekodiert in Maps mit String-Schlüsseln und den Feldnamen der API (`sent["id"]`), die API-Referenz beschreibt sie also Feld für Feld. Mit `BillionSend.Client.request(client, "GET", "/path", query: [...])` erreichen Sie alles, was die Funktionen nicht abdecken.

## Idempotenz und Wiederholungsversuche

Die acht Versand-Funktionen (`Emails.send`, `Emails.batch`, `Emails.Receiving.reply` und `.forward`, `Inboxes.send`, `Inboxes.Drafts.send`, `Inboxes.Threads.Emails.reply` und `.forward`) senden immer einen `Idempotency-Key`. Ohne `idempotency_key:` denkt sich jeder Aufruf einen aus (eine UUID), den seine Wiederholungen weiterverwenden. Ein erneuter Versuch nach einer abgebrochenen Verbindung sendet also nie doppelt, und Ihr eigener Schlüssel macht auch eine Wiederholung aus einem anderen Prozess sicher. Derselbe Schlüssel mit einer anderen Anfrage wird mit einem `BillionSend.ConflictError` abgelehnt.

Fehlschläge, bei denen sich ein neuer Versuch lohnt, werden standardmäßig zweimal wiederholt: 429, 5xx, keine Antwort (Verbindungsfehler, Timeout) 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 Idempotenzschlüssel, wie sie jeder Versand trägt. Der Client wartet so lange, wie `Retry-After` es verlangt, und gibt den Fehler sofort zurück, wenn es mehr als eine Minute verlangt. Sonst weicht er exponentiell von 0,5 s bis 8 s zurück, mit Jitter. `max_retries:` legen Sie am Client fest (`0` schaltet Wiederholungen ab), und der aufrufende Prozess schläft zwischen den Versuchen.

## Fehler

Ein fehlgeschlagener Aufruf liefert `{:error, error}` mit einer Exception-Struct: `BillionSend.ValidationError` (400, 422), `AuthenticationError` (401 oder kein Schlüssel konfiguriert, dann ist `name` auf `missing_api_key` gesetzt, bevor etwas gesendet wird), `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). `BillionSend.Error` ist jeder andere Status. Jede trägt `status_code` (`nil`, wenn es keine Antwort gab), `name` (den Fehlernamen der API), `message` und `request_id`, den `x-request-id` der Antwort, der zugleich die ID der Anfrage auf der Logs-Seite des Dashboards ist. `BillionSend.Errors.error?/1` unterscheidet jede von ihnen von anderen Termen.

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

## Listen

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

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

## Das Postfach eines Agenten

Warten Sie im [Ereignis-Stream](/docs/de/inboxes) auf neue Mails und antworten Sie in ihrem Thread:

```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))  # ein StreamGapEvent: Ereignisse können fehlen, Threads erneut lesen
|> 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` öffnet den Stream zuerst, ein abgelehnter Stream (ein widerrufener Schlüssel, ein auf ein Postfach beschränkter Schlüssel, der den Stream des Teams verlangt) ist also sofort ein `{:error, error}`. Zurück kommt ein träges `Enumerable` aus `BillionSend.InboxStreamEvent`-Structs (`id`, `event`, etwa `"inbox.email.received"`, und `data`, also `"type"`, `"created_at"`, `"inbox_id"` und `"data"` der Webhook-Nutzdaten) und `BillionSend.StreamGapEvent`-Structs. Der Stream verbindet sich mit `Last-Event-ID` neu, wenn die Verbindung abbricht, und spielt Verpasstes nach. Behalten Sie die `id` des letzten Ereignisses, das Sie verarbeitet haben, und übergeben Sie sie 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) steuert das Wiederverbinden, das vor jedem Versuch eine Sekunde wartet oder so lange, wie das Feld `retry` des Servers verlangt. Danach löst die Enumeration den Fehler der API für den letzten Versuch aus, oder `BillionSend.APIConnectionError`, wenn sie keine Antwort bekam. Der Stream eines Postfachs endet, nachdem dieses Postfach gelöscht wurde oder abgelaufen ist. `BillionSend.Inboxes.Events.stream/2` folgt jedem Postfach, das der Schlüssel lesen kann. Enumerieren Sie einen Stream nur einmal, in dem Prozess, der ihn geöffnet hat: Bricht man die Enumeration ab (`Enum.take/2`, `Stream.take_while/2`), schließt das die Verbindung.

## Webhooks verifizieren

`BillionSend.verify_webhook/4` prüft Signatur und Zeitstempel einer [Webhook](/docs/de/concepts/webhooks)-Zustellung mit dem `whsec_`-Secret des Endpunkts und liefert `{:ok, event}` mit dem geparsten Ereignis oder `{:error, %BillionSend.WebhookVerificationError{}}`. Übergeben Sie den Body genau so, wie er angekommen ist, vor jedem JSON-Parsen. Die Header können eine Map oder eine Liste von Paaren sein, etwa `conn.req_headers`, mit Namen in jeder Schreibweise:

```elixir
# Phoenix: den Roh-Body aufbewahren (ein Plug.Parsers-:body_reader, der ihn in conn.assigns ablegt)
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
```

Eine Zustellung, die älter als fünf Minuten ist, wird abgelehnt (`tolerance:` in Sekunden ändert das), und während einer Rotation des Secrets verifiziert jedes der beiden Secrets. `verify_webhook!/4` liefert das Ereignis oder löst einen Fehler aus. Ein Secret, das kein `whsec_`-Secret ist, löst `ArgumentError` aus.
