Saltar al contenido
Esc
↑↓navegar↵abrir⌘Jvista previa
En esta página

SDK de Rust

Envía emails, trabaja con una bandeja de entrada y verifica webhooks desde Rust con el crate asíncrono billionsend: toda la API, reintentos e idempotencia.

El crate billionsend es el cliente de BillionSend para Rust. Cubre todas las operaciones de la referencia de la API: envío, dominios, contactos, envíos masivos, plantillas, webhooks, bandejas de entrada con sus hilos y borradores, eventos de bandeja en tiempo real y registro de agentes. Sus métodos se generan a partir del documento OpenAPI de la API. El código fuente está en billionsend/billionsend-rust, en GitHub.

Instalar

Requiere Rust 1.85 o superior. El crate es asíncrono, sobre tokio y reqwest, con TLS mediante rustls (la característica native-tls usa en su lugar la biblioteca TLS de la plataforma); futures-util maneja los flujos de listas y de eventos.

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

Enviar un email

use billionsend::BillionSend;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), billionsend::Error> {
    let bs = BillionSend::from_env(); // lee 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_...") recibe la clave directamente; BillionSend::builder() define el resto con .api_key, .base_url, .timeout (por intento, 60 s por defecto), .max_retries, .header y .http_client (tu propio reqwest::Client), y se cierra con .build()?. BILLIONSEND_BASE_URL sustituye la URL de la API.

Nombres de los métodos

Cada operación es un método con el nombre de su id en la referencia de la API, y cada segmento separado por puntos es una llamada en snake_case: emails.send es bs.emails().send(..) y emails.receiving.attachments.list es bs.emails().receiving().attachments().list(..). emails.metrics es bs.emails().metrics().get(), junto a links(), countries() y clients().

Un método recibe los parámetros de ruta en orden y después el cuerpo de la petición: cualquier valor que implemente serde::Serialize, como un json!, con los nombres de campo propios de la API. Devuelve un constructor de peticiones cuyos setters son los parámetros de consulta y de cabecera (.limit(100), .after(id), .batch_validation("strict")); al hacerle await, envía la petición. La respuesta es un serde_json::Value; termina con .json::<T>() para leerla en tu propio tipo Deserialize, o con .raw() para conservar el estado y las cabeceras.

Idempotencia y reintentos

Las ocho operaciones de envío (emails().send, emails().batch, respuestas y reenvíos de correo recibido, inboxes().send, inboxes().drafts().send, respuestas y reenvíos de hilos) siempre mandan un Idempotency-Key. Sin .idempotency_key(..), cada llamada se inventa una que sus reintentos reutilizan, así que reintentar tras un timeout nunca envía dos veces. Una clave tuya también hace segura la repetición desde otro proceso.

Los fallos que merecen otro intento se reintentan dos veces por defecto: 429, 5xx, timeouts, errores de red y el 409 concurrent_idempotent_requests que se devuelve mientras el primer intento con la misma clave sigue en curso. Solo se reintentan las peticiones que se pueden repetir sin riesgo: GET, PUT, DELETE y las operaciones de envío. El cliente espera lo que pida Retry-After y devuelve el error en lugar de esperar si pide más de un minuto; si no, aumenta la espera de forma exponencial de 500 ms a 8 s, con una variación aleatoria de hasta una cuarta parte. Todos los constructores de peticiones aceptan además .timeout(..), .max_retries(..) y .header(..) para esa llamada.

Errores

Una llamada fallida devuelve un billionsend::Error, con una variante por tipo: Validation (400, 422), Authentication (401, o no hay clave configurada), PermissionDenied (403), NotFound (404), Conflict (409), RateLimit (429, con retry_after() en segundos), Server (5xx), Api (cualquier otro estado, o una respuesta que no es el JSON esperado), Connection (sin respuesta), Timeout (el intento agotó el tiempo), WebhookVerification y Application (la crea el cliente sin hacer ninguna llamada, por ejemplo ante un parámetro de ruta vacío). Todas las variantes tienen status_code(), name() (el nombre del error de la API), message() y request_id(), el x-request-id de la respuesta, que es el id de la petición en la página Registros del panel.

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

Listas

Los métodos de lista devuelven una página. Cada lista con cursor tiene además .into_stream(), un flujo de sus elementos que va pidiendo las páginas siguientes, hacia atrás si se define .before(..):

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 bandeja de entrada de un agente

Espera email nuevo en el flujo de eventos y responde en su hilo:

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 {
    // Un error aquí: se agotó la reconexión, o la clave dejó de funcionar.
    let event = match item? {
        InboxStreamItem::Event(event) => event,
        // Puede faltar algún evento: vuelve a leer los hilos.
        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?;
}

El flujo se reconecta con Last-Event-ID cuando se corta la conexión y reenvía lo que se perdió. Guarda events.last_event_id() y pásalo de nuevo con .last_event_id(..) para retomarlo tras un reinicio. Un InboxStreamItem::Gap llega una sola vez, cuando el flujo se retoma desde hace más de 24 horas. .max_reconnects(..) (reconexiones fallidas seguidas antes de rendirse, 5 por defecto), .reconnect_delay(..) y .reconnect(false) ajustan la reconexión. El flujo de una bandeja termina cuando esa bandeja se elimina o caduca; bs.inboxes().events().stream() sigue todas las bandejas del equipo, con una clave de todo el equipo.

Verificar webhooks

verify_webhook comprueba la firma y la marca de tiempo de una entrega de webhook con el secreto whsec_ del endpoint y devuelve el evento ya interpretado; cualquier fallo es un Error::WebhookVerification. Pasa el cuerpo exactamente como llegó. Las cabeceras pueden ser un HeaderMap de http, como en axum, un HashMap o una lista de pares:

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

Una entrega de más de cinco minutos se rechaza (WebhookVerifier::new(secret)?.tolerance(..) define otro plazo) y, durante la rotación de un secreto, sirve cualquiera de los dos.

Registro de agentes

let signup = BillionSend::from_env()
    .agent()
    .signup(&json!({ "human_email": "owner@acme.dev", "name": "Support agent" }))
    .await?;
println!("{}", signup["inbox"]["email_address"]);

La llamada no necesita clave de API; la respuesta trae la clave nueva y la bandeja de entrada. Consulta Registro de agentes para saber qué puede hacer una cuenta sin reclamar.

¿Te ha resultado útil esta página?