Rust-SDK
E-Mails senden, Postfach bedienen und Webhooks verifizieren mit dem asynchronen Crate billionsend: jede API-Operation, Wiederholungen, Idempotenzschlüssel.
Das Crate billionsend ist der BillionSend-Client für Rust. Es deckt jede Operation der API-Referenz 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.
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.
cargo add billionsend serde_json futures-util
cargo add tokio --features macros,rt-multi-thread
E-Mail senden
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, 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.
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:
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 auf neue Mails und antworten Sie in ihrem Thread:
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-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:
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
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.