---
title: Rust SDK
description: 用异步的 billionsend crate 在 Rust 里发送邮件、使用收件箱、验证 Webhook，覆盖全部 API 操作，内置重试与幂等键。
ai:
  exclude: true
---

`billionsend` crate 是 BillionSend 面向 Rust 的客户端。它覆盖 [API 参考](/docs/zh-hans/api-reference)里的全部操作：发送、域名、联系人、群发、模板、Webhook、带会话和草稿的收件箱、实时的收件箱事件，以及 Agent 注册。它的方法由 API 的 OpenAPI 文档生成。源码在 GitHub 上的 [billionsend/billionsend-rust](https://github.com/billionsend/billionsend-rust)。

## 安装

需要 Rust 1.85 或更高版本。这个 crate 是异步的，基于 `tokio` 和 `reqwest`，TLS 通过 rustls 提供（`native-tls` 特性则改用平台自带的 TLS 库）；`futures-util` 驱动列表流和事件流。

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

## 发送邮件

```rust
use billionsend::BillionSend;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), billionsend::Error> {
    let bs = BillionSend::from_env(); // 读取 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_...")` 直接传入密钥；`BillionSend::builder()` 用 `.api_key`、`.base_url`、`.timeout`（每次尝试，默认 60 s）、`.max_retries`、`.header` 和 `.http_client`（你自己的 `reqwest::Client`）设置其余选项，最后调用 `.build()?`。`BILLIONSEND_BASE_URL` 可以覆盖 API 地址。

## 方法命名

每个操作都是一个方法，名字取自它在 [API 参考](/docs/zh-hans/api-reference)里的 id，每个用点分隔的部分变成一次 snake_case 调用：`emails.send` 是 `bs.emails().send(..)`，`emails.receiving.attachments.list` 是 `bs.emails().receiving().attachments().list(..)`。`emails.metrics` 是 `bs.emails().metrics().get()`，旁边还有 `links()`、`countries()` 和 `clients()`。

一个方法依次接收：路径参数（按顺序），然后是请求体：任何实现了 `serde::Serialize` 的值，例如 `json!` 值，字段名就是 API 自己的字段名。它返回一个请求构建器，查询和请求头参数就是它的设置方法（`.limit(100)`、`.after(id)`、`.batch_validation("strict")`），`await` 它才会发出请求。响应是一个 `serde_json::Value`；以 `.json::<T>()` 结尾，可以把它读成你自己的 `Deserialize` 类型，以 `.raw()` 结尾则保留状态码和响应头。

## 幂等与重试

八个发送操作（`emails().send`、`emails().batch`、收到邮件的回复与转发、`inboxes().send`、`inboxes().drafts().send`、会话的回复与转发）总是会带上 `Idempotency-Key`。如果没有 `.idempotency_key(..)`，每次调用会自己生成一个，它的重试沿用这个密钥，所以超时后的重试不会重复发送；你自己的密钥还能让另一个进程里的重复调用也保持安全。

值得重试的失败默认会重试两次：429、5xx、超时、网络错误，以及同一个密钥的第一次请求仍在运行时返回的 `409 concurrent_idempotent_requests`。只有可以安全重复的请求才会重试：`GET`、`PUT`、`DELETE` 和发送操作。客户端按 `Retry-After` 的要求等待，要求等待超过一分钟时直接返回错误；其余情况从 500 ms 起按指数退避，最多 8 s，并加上最多四分之一的随机抖动。每个请求构建器还接受 `.timeout(..)`、`.max_retries(..)` 和 `.header(..)`，只对这次调用生效。

## 错误

失败的调用返回一个 `billionsend::Error`，每种类型对应一个变体：`Validation`（400、422）、`Authentication`（401，或没有配置密钥）、`PermissionDenied`（403）、`NotFound`（404）、`Conflict`（409）、`RateLimit`（429，`retry_after()` 以秒为单位）、`Server`（5xx）、`Api`（任何其他状态，或不是预期 JSON 的响应）、`Connection`（没有响应）、`Timeout`（这次尝试超时）、`WebhookVerification`，以及 `Application`（由客户端在没有发起调用的情况下生成，例如路径参数为空）。每个变体都有 `status_code()`、`name()`（API 的错误名）、`message()` 和 `request_id()`；`request_id()` 返回响应的 `x-request-id`，也就是这个请求在控制台日志页面上的 id。

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

## 列表

列表方法返回一页。每个游标列表还有 `.into_stream()`，它是由各项组成的流，会在迭代过程中获取后续的页；设置了 `.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());
}
```

## Agent 的收件箱

在[事件流](/docs/zh-hans/inboxes)上等待新邮件，并在它所在的会话里回复：

```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 {
    // 这里出错：重连次数用尽，或密钥已失效。
    let event = match item? {
        InboxStreamItem::Event(event) => event,
        // 事件可能有缺失：重新读取会话。
        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?;
}
```

连接断开时，事件流会带着 `Last-Event-ID` 重新连接，并补上错过的事件；保存 `events.last_event_id()`，再用 `.last_event_id(..)` 传回去，就能在重启之后继续。从 24 小时之前的位置恢复时，会收到一次 `InboxStreamItem::Gap`。`.max_reconnects(..)`（放弃之前连续失败的重连次数，默认 5）、`.reconnect_delay(..)` 和 `.reconnect(false)` 用来调整重连行为。单个收件箱的事件流在该收件箱被删除或过期后结束；用团队级密钥时，`bs.inboxes().events().stream()` 会跟随团队的所有收件箱。

## 验证 Webhook

`verify_webhook` 用端点的 `whsec_` 密钥检查一次 [Webhook](/docs/zh-hans/concepts/webhooks) 投递的签名和时间戳，并返回解析后的事件；任何问题都会得到 `Error::WebhookVerification`。传入的请求体必须与收到时完全一致。请求头可以是 `http` 的 `HeaderMap`（如 axum 里那样）、`HashMap`，或一组键值对：

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

超过五分钟的投递会被拒绝（`WebhookVerifier::new(secret)?.tolerance(..)` 可以设置另一个时间窗口），密钥轮换期间，新旧两个密钥都能通过验证。

## Agent 注册

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

这个调用不需要 API 密钥；响应里带有新的密钥和收件箱。未认领的账号可以做什么，见 [Agent 注册](/docs/zh-hans/agent-signup)。
