Pular para o conteúdo
Esc
↑↓navegar↵abrir⌘Jpré-visualizar
Nesta página

SDK para Rust

Use o BillionSend em Rust com o crate billionsend.

O crate billionsend é o cliente do BillionSend para Rust. Ele cobre todas as operações da referência da API: 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 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.

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

Enviar um 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": ["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, 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.

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:

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 e responda na conversa:

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

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.

Esta página foi útil?