---
title: SDK de Rust
description: "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."
ai:
  exclude: true
---

El crate `billionsend` es el cliente de BillionSend para Rust. Cubre todas las operaciones de la [referencia de la API](/docs/es/api-reference): 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](https://github.com/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.

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

## Enviar un email

```rust
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](/docs/es/api-reference), 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.

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

## 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(..)`:

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

Espera email nuevo en el [flujo de eventos](/docs/es/inboxes) y responde en su hilo:

```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 {
    // 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](/docs/es/concepts/webhooks) 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:

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

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

```rust
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](/docs/es/agent-signup) para saber qué puede hacer una cuenta sin reclamar.
