Aller au contenu
Esc
↑↓naviguer↵ouvrir⌘Japerçu
Sur cette page

SDK Rust

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.

Le crate billionsend est le client BillionSend pour Rust. Il couvre toutes les opérations de la référence de l’API : 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.

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.

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

Envoyer un e-mail

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, 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.

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 :

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 et répondez dans leur fil :

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

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

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 pour ce qu’un compte non réclamé peut faire.

Cette page vous a-t-elle été utile ?