---
title: Rust SDK
description: 用非同步的 billionsend crate 在 Rust 中傳送郵件、操作收件匣、驗證 Webhook，涵蓋全部 API 操作，內建重試與冪等鍵。
ai:
  exclude: true
---

`billionsend` crate 是 BillionSend 面向 Rust 的用戶端。它涵蓋 [API 參考](/docs/zh-hant/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 秒）、`.max_retries`、`.header` 和 `.http_client`（你自己的 `reqwest::Client`）設定其餘選項，最後呼叫 `.build()?`。`BILLIONSEND_BASE_URL` 可以覆寫 API 網址。

## 方法命名

每個操作都是一個方法，以它在 [API 參考](/docs/zh-hant/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 自己的欄位名稱。它回傳一個請求建構器，它的 setter 就是查詢與標頭參數（`.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 毫秒到 8 秒採指數退避，並加上最多四分之一的抖動。每個請求建構器還接受 `.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-hant/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-hant/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-hant/agent-signup)。
