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

Das Crate `billionsend` ist der BillionSend-Client für Rust. 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. Seine Methoden werden aus dem OpenAPI-Dokument der API generiert. Der Quellcode liegt auf GitHub unter [billionsend/billionsend-rust](https://github.com/billionsend/billionsend-rust).

## Installation

Erfordert Rust 1.85 oder neuer. Das Crate ist asynchron, auf `tokio` und `reqwest` aufgebaut, mit TLS über rustls (das Feature `native-tls` nutzt stattdessen die TLS-Bibliothek der Plattform). `futures-util` treibt die Listen- und Ereignis-Streams an.

```sh
cargo add billionsend serde_json futures-util
cargo add tokio --features macros,rt-multi-thread
```

## E-Mail senden

```rust
use billionsend::BillionSend;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), billionsend::Error> {
    let bs = BillionSend::from_env(); // liest BILLIONSEND_API_KEY

    let sent = bs
        .emails()
        .send(&json!({
            "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")
        .await?;
    println!("{}", sent["id"].as_str().unwrap_or_default());
    Ok(())
}
```

`BillionSend::new("bs_...")` nimmt den Schlüssel direkt entgegen. `BillionSend::builder()` legt den Rest mit `.api_key`, `.base_url`, `.timeout` (pro Versuch, Standard 60 s), `.max_retries`, `.header` und `.http_client` (Ihr eigener `reqwest::Client`) fest, danach `.build()?`. `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), jedes durch Punkte getrennte Segment ein Aufruf in snake_case: `emails.send` ist `bs.emails().send(..)`, `emails.receiving.attachments.list` ist `bs.emails().receiving().attachments().list(..)`. `emails.metrics` ist `bs.emails().metrics().get()`, neben `links()`, `countries()` und `clients()`.

Eine Methode nimmt die Pfadparameter der Reihe nach und danach den Request-Body: alles, was `serde::Serialize` umsetzt, etwa ein `json!`-Wert, mit den Feldnamen der API. Sie liefert einen Request-Builder, dessen Setter die Query- und Header-Parameter sind (`.limit(100)`, `.after(id)`, `.batch_validation("strict")`), und mit await wird die Anfrage gesendet. Die Antwort ist ein `serde_json::Value`. Mit `.json::<T>()` am Ende lesen Sie sie in Ihren eigenen `Deserialize`-Typ, mit `.raw()` behalten Sie Status und Header.

## 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 die Versand-Operationen. Der Client wartet so lange, wie `Retry-After` es verlangt, und liefert stattdessen den Fehler, wenn es mehr als eine Minute verlangt. Sonst weicht er exponentiell von 500 ms bis 8 s zurück, abzüglich bis zu einem Viertel Jitter. Jeder Request-Builder nimmt außerdem `.timeout(..)`, `.max_retries(..)` und `.header(..)` für diesen Aufruf entgegen.

## Fehler

Ein fehlgeschlagener Aufruf liefert einen `billionsend::Error`, eine Variante je Art: `Validation` (400, 422), `Authentication` (401 oder kein Schlüssel konfiguriert), `PermissionDenied` (403), `NotFound` (404), `Conflict` (409), `RateLimit` (429, mit `retry_after()` in Sekunden), `Server` (5xx), `Api` (jeder andere Status oder eine Antwort, die nicht das erwartete JSON ist), `Connection` (keine Antwort), `Timeout` (der Versuch hat das Zeitlimit überschritten), `WebhookVerification` und `Application` (vom Client ohne Aufruf erzeugt, etwa bei einem leeren Pfadparameter). Jede Variante hat `status_code()`, `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.

```rust
use billionsend::Error;

match bs.emails().get(id).await {
    Ok(email) => println!("{}", email["last_event"]),
    Err(Error::NotFound(_)) => println!("no such email"),
    Err(error) => eprintln!(
        "{:?} {}: {} (request {:?})",
        error.status_code(),
        error.name(),
        error.message(),
        error.request_id(),
    ),
}
```

## Listen

Listen-Methoden liefern eine Seite. Jede Cursor-Liste hat außerdem `.into_stream()`, einen Stream ihrer Einträge, der die nächsten Seiten nach und nach abruft, rückwärts, wenn `.before(..)` gesetzt ist:

```rust
use futures_util::TryStreamExt;

let mut contacts = bs.contacts().list().limit(100).into_stream();
while let Some(contact) = contacts.try_next().await? {
    println!("{}", contact["email"].as_str().unwrap_or_default());
}
```

## Das Postfach eines Agenten

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

```rust
use billionsend::InboxStreamItem;
use futures_util::StreamExt;
use serde_json::json;

let mut events = bs
    .inboxes()
    .events()
    .stream_inbox("support@acme.dev")
    .types("inbox.email.received")
    .await?;

while let Some(item) = events.next().await {
    // Ein Fehler hier: Das Wiederverbinden ist ausgeschöpft, oder der Schlüssel funktioniert nicht mehr.
    let event = match item? {
        InboxStreamItem::Event(event) => event,
        // Ereignisse können fehlen: Threads erneut lesen.
        InboxStreamItem::Gap(_) => continue,
    };
    let data = &event.data;
    let (Some(inbox_id), Some(thread_id), Some(email_id)) = (
        data["inbox_id"].as_str(),
        data["data"]["thread_id"].as_str(),
        data["data"]["email_id"].as_str(),
    ) else {
        continue;
    };
    bs.inboxes()
        .threads()
        .emails()
        .reply(inbox_id, thread_id, email_id, &json!({ "text": "Thanks, we are on it." }))
        .idempotency_key(format!("reply/{email_id}"))
        .await?;
}
```

Der Stream verbindet sich mit `Last-Event-ID` neu, wenn die Verbindung abbricht, und spielt Verpasstes nach. Behalten Sie `events.last_event_id()` und übergeben Sie es mit `.last_event_id(..)` zurück, um nach einem Neustart fortzusetzen. Ein `InboxStreamItem::Gap` kommt einmal, wenn der Stream von weiter als 24 Stunden zurück fortgesetzt wird. `.max_reconnects(..)` (fehlgeschlagene Wiederverbindungen in Folge, bevor aufgegeben wird, Standard 5), `.reconnect_delay(..)` und `.reconnect(false)` steuern das Wiederverbinden. Der Stream eines Postfachs endet, nachdem dieses Postfach gelöscht wurde oder abgelaufen ist. `bs.inboxes().events().stream()` folgt jedem Postfach des Teams, mit einem teamweiten Schlüssel.

## Webhooks verifizieren

`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. Alles, was nicht stimmt, ist ein `Error::WebhookVerification`. Übergeben Sie den Body genau so, wie er angekommen ist. Die Header können eine `HeaderMap` aus `http` sein, wie in axum, eine `HashMap` oder eine Liste von Paaren:

```rust
use axum::body::Bytes;
use axum::http::{HeaderMap, StatusCode};
use axum::{Router, routing::post};

async fn webhook(headers: HeaderMap, body: Bytes) -> StatusCode {
    let secret = std::env::var("BILLIONSEND_WEBHOOK_SECRET").unwrap_or_default();
    match billionsend::verify_webhook(&body, &headers, &secret) {
        Ok(event) => {
            println!("{}", event["type"]);
            StatusCode::NO_CONTENT
        }
        Err(_) => StatusCode::BAD_REQUEST,
    }
}

fn app() -> Router {
    Router::new().route("/webhooks/billionsend", post(webhook))
}
```

Eine Zustellung, die älter als fünf Minuten ist, wird abgelehnt (`WebhookVerifier::new(secret)?.tolerance(..)` legt ein anderes Zeitfenster fest), und während einer Rotation des Secrets verifiziert jedes der beiden Secrets.

## Agent-Registrierung

```rust
let signup = BillionSend::from_env()
    .agent()
    .signup(&json!({ "human_email": "owner@acme.dev", "name": "Support agent" }))
    .await?;
println!("{}", 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).
