---
title: SDK para Rust
description: Use o BillionSend em Rust com o crate billionsend.
ai:
  exclude: true
---

O crate `billionsend` é o cliente do BillionSend para Rust. Ele cobre todas as operações da [referência da API](/docs/pt-br/api-reference): envio, domínios, contatos, broadcasts, templates, webhooks, caixas de entrada com suas conversas e rascunhos, eventos das caixas de entrada em tempo real e cadastro de agentes. Os seus métodos são gerados a partir do documento OpenAPI da API. O código-fonte está em [billionsend/billionsend-rust](https://github.com/billionsend/billionsend-rust) no GitHub.

## Instalar

Requer Rust 1.85 ou mais recente. O crate é assíncrono, sobre `tokio` e `reqwest`, com TLS via rustls (a feature `native-tls` usa a biblioteca TLS da plataforma no lugar); o `futures-util` move os fluxos de listas e de eventos.

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

## Enviar um 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": ["ana@example.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_...")` recebe a chave diretamente; `BillionSend::builder()` define o resto com `.api_key`, `.base_url`, `.timeout` (por tentativa, padrão de 60 s), `.max_retries`, `.header` e `.http_client` (o seu próprio `reqwest::Client`), e depois `.build()?`. `BILLIONSEND_BASE_URL` substitui a URL da API.

## Nomes dos métodos

Cada operação é um método com o nome do seu id na [referência da API](/docs/pt-br/api-reference), cada segmento separado por ponto virando uma chamada em snake_case: `emails.send` é `bs.emails().send(..)`, `emails.receiving.attachments.list` é `bs.emails().receiving().attachments().list(..)`. `emails.metrics` é `bs.emails().metrics().get()`, ao lado de `links()`, `countries()` e `clients()`.

Um método recebe os parâmetros de caminho em ordem e depois o corpo da requisição: qualquer coisa que implemente `serde::Serialize`, como um valor `json!`, com os nomes de campo da própria API. Ele devolve um construtor de requisição cujos setters são os parâmetros de consulta e de cabeçalho (`.limit(100)`, `.after(id)`, `.batch_validation("strict")`), e aguardá-lo com `.await` envia a requisição. A resposta é um `serde_json::Value`; termine com `.json::<T>()` para lê-la no seu próprio tipo `Deserialize`, ou com `.raw()` para ficar também com o status e os cabeçalhos.

## Idempotência e novas tentativas

As oito operações de envio (`emails().send`, `emails().batch`, respostas e encaminhamentos de e-mails recebidos, `inboxes().send`, `inboxes().drafts().send`, respostas e encaminhamentos em conversas) sempre enviam um `Idempotency-Key`. Sem `.idempotency_key(..)`, cada chamada cria uma chave que as suas novas tentativas reutilizam, então uma nova tentativa depois de um timeout nunca envia duas vezes; a sua própria chave também deixa segura uma repetição vinda de outro processo.

Falhas que valem nova tentativa são repetidas duas vezes por padrão: 429, 5xx, timeouts, erros de rede e o `409 concurrent_idempotent_requests` respondido enquanto a primeira tentativa com a mesma chave ainda está em andamento. Só são repetidas as requisições seguras de repetir: `GET`, `PUT`, `DELETE` e as operações de envio. O cliente espera o que o `Retry-After` pede e, quando ele pede mais de um minuto, devolve o erro em vez de esperar; senão recua exponencialmente de 500 ms até 8 s, menos até um quarto de variação aleatória. Todo construtor de requisição também aceita `.timeout(..)`, `.max_retries(..)` e `.header(..)` para aquela chamada.

## Erros

Uma chamada que falha devolve um `billionsend::Error`, com uma variante para cada tipo: `Validation` (400, 422), `Authentication` (401, ou nenhuma chave configurada), `PermissionDenied` (403), `NotFound` (404), `Conflict` (409), `RateLimit` (429, com `retry_after()` em segundos), `Server` (5xx), `Api` (qualquer outro status, ou uma resposta que não é o JSON esperado), `Connection` (sem resposta), `Timeout` (a tentativa estourou o tempo), `WebhookVerification` e `Application` (criado pelo cliente sem fazer a chamada, como um parâmetro de caminho vazio). Toda variante tem `status_code()`, `name()` (o nome do erro na API), `message()` e `request_id()`, o `x-request-id` da resposta, que é o id da requisição na página Logs do painel.

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

Os métodos de lista devolvem uma página. Toda lista com cursor também tem `.into_stream()`, um fluxo dos seus itens que busca as páginas seguintes conforme avança, para trás quando `.before(..)` está definido:

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

## A caixa de entrada de um agente

Espere e-mails novos no [fluxo de eventos](/docs/pt-br/inboxes) e responda na conversa:

```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?;
}
```

O fluxo se reconecta com `Last-Event-ID` quando a conexão cai e reenvia o que perdeu; guarde `events.last_event_id()` e passe-o de volta com `.last_event_id(..)` para retomar depois de reiniciar. Um `InboxStreamItem::Gap` chega uma vez quando o fluxo é retomado de mais de 24 horas atrás. `.max_reconnects(..)` (reconexões que falham seguidas antes de desistir, padrão 5), `.reconnect_delay(..)` e `.reconnect(false)` ajustam a reconexão. O fluxo de uma caixa termina depois que essa caixa é excluída ou expira; `bs.inboxes().events().stream()` acompanha todas as caixas da equipe, com uma chave de toda a equipe.

## Verificar webhooks

`verify_webhook` confere a assinatura e o horário de uma entrega de [webhook](/docs/pt-br/concepts/webhooks) com o segredo `whsec_` do endpoint e devolve o evento já interpretado; qualquer problema vira um `Error::WebhookVerification`. Passe o corpo exatamente como chegou. Os cabeçalhos podem ser um `HeaderMap` do `http`, como no axum, um `HashMap` ou uma 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))
}
```

Uma entrega com mais de cinco minutos é recusada (`WebhookVerifier::new(secret)?.tolerance(..)` define outra janela), e durante a rotação de um segredo qualquer um dos dois verifica.
