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

Le crate `billionsend` est le client BillionSend pour Rust. 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. Ses méthodes sont générées à partir du document OpenAPI de l'API. Le code source est sur GitHub : [billionsend/billionsend-rust](https://github.com/billionsend/billionsend-rust).

## Installer

Nécessite Rust 1.85 ou plus récent. Le crate est asynchrone, bâti sur `tokio` et `reqwest`, avec TLS via rustls (la fonctionnalité `native-tls` utilise à la place la bibliothèque TLS de la plateforme) ; `futures-util` pilote les flux de listes et d'événements.

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

## Envoyer un e-mail

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

#[tokio::main]
async fn main() -> Result<(), billionsend::Error> {
    let bs = BillionSend::from_env(); // reads 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_...")` prend la clé directement ; `BillionSend::builder()` règle le reste avec `.api_key`, `.base_url`, `.timeout` (par tentative, 60 s par défaut), `.max_retries`, `.header` et `.http_client` (votre propre `reqwest::Client`), puis `.build()?`. `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), chaque segment séparé par un point devenant un appel en snake_case : `emails.send` devient `bs.emails().send(..)`, `emails.receiving.attachments.list` devient `bs.emails().receiving().attachments().list(..)`. `emails.metrics` devient `bs.emails().metrics().get()`, à côté de `links()`, `countries()` et `clients()`.

Une méthode prend, dans l'ordre, les paramètres de chemin, puis le corps de la requête : tout ce qui implémente `serde::Serialize`, comme une valeur `json!`, avec les noms de champ de l'API elle-même. Elle renvoie un constructeur de requête dont les setters sont les paramètres de requête et d'en-tête (`.limit(100)`, `.after(id)`, `.batch_validation("strict")`), et attendre son résultat envoie la requête. La réponse est un `serde_json::Value` ; terminez par `.json::<T>()` pour la lire dans votre propre type `Deserialize`, ou par `.raw()` pour garder le statut et les en-têtes.

## 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 les opérations d'envoi. Le client attend ce que demande `Retry-After` et renvoie l'erreur à la place lorsqu'il demande plus d'une minute ; sinon il espace les tentatives de façon exponentielle, de 500 ms à 8 s, diminuées d'une gigue d'un quart au plus. Chaque constructeur de requête accepte aussi `.timeout(..)`, `.max_retries(..)` et `.header(..)` pour cet appel.

## Erreurs

Un appel qui échoue renvoie une `billionsend::Error`, avec une variante par type d'erreur : `Validation` (400, 422), `Authentication` (401, ou aucune clé configurée), `PermissionDenied` (403), `NotFound` (404), `Conflict` (409), `RateLimit` (429, avec `retry_after()` en secondes), `Server` (5xx), `Api` (tout autre statut, ou une réponse qui n'est pas le JSON attendu), `Connection` (aucune réponse), `Timeout` (la tentative a dépassé son délai), `WebhookVerification` et `Application` (fabriquée par le client sans appel, par exemple pour un paramètre de chemin vide). Chaque variante a `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.

```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(),
    ),
}
```

## Listes

Les méthodes de liste renvoient une page. Chaque liste à curseur dispose aussi de `.into_stream()`, un flux de ses éléments qui va chercher les pages suivantes au fur et à mesure, en remontant lorsque `.before(..)` est défini :

```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());
}
```

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

```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 {
    // An error here: reconnecting ran out, or the key stopped working.
    let event = match item? {
        InboxStreamItem::Event(event) => event,
        // Events may be missing: read the threads again.
        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?;
}
```

Le flux se reconnecte avec `Last-Event-ID` lorsque la connexion tombe et rejoue ce qu'il a manqué. Gardez `events.last_event_id()` et repassez-le avec `.last_event_id(..)` pour reprendre après un redémarrage. Un `InboxStreamItem::Gap` arrive une seule fois lorsque le flux reprend depuis plus de 24 heures en arrière. `.max_reconnects(..)` (nombre de reconnexions ratées d'affilée avant d'abandonner, 5 par défaut), `.reconnect_delay(..)` et `.reconnect(false)` règlent la reconnexion. Le flux d'une boîte de réception se termine une fois cette boîte supprimée ou expirée ; `bs.inboxes().events().stream()` suit toutes les boîtes de l'équipe, avec une clé valable pour toute l'équipe.

## Vérifier les webhooks

`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é ; tout problème donne une `Error::WebhookVerification`. Passez le corps exactement tel qu'il est arrivé. Les en-têtes peuvent être une `HeaderMap` de `http`, comme dans axum, une `HashMap` ou une liste de paires :

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

Une livraison de plus de cinq minutes est refusée (`WebhookVerifier::new(secret)?.tolerance(..)` définit une autre fenêtre), et pendant la rotation d'un secret, l'un ou l'autre secret est accepté.

## Inscription d'un agent

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