跳到内容
Esc
↑↓导航↵打开⌘J预览
本页内容

Rust SDK

用非同步的 billionsend crate 在 Rust 中傳送郵件、操作收件匣、驗證 Webhook,涵蓋全部 API 操作,內建重試與冪等鍵。

billionsend crate 是 BillionSend 面向 Rust 的用戶端。它涵蓋 API 參考中的全部操作:傳送、網域、聯絡人、群發、範本、Webhook、含會話串與草稿的收件匣、即時的收件匣事件,以及 Agent 註冊。它的方法是由 API 的 OpenAPI 文件產生的。原始碼在 GitHub 上的 billionsend/billionsend-rust。

安裝

需要 Rust 1.85 或更新版本。這個 crate 是非同步的,建立在 tokio 和 reqwest 上,TLS 透過 rustls 提供(native-tls 功能改用平台的 TLS 函式庫);futures-util 驅動列表和事件串流。

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

傳送郵件

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 參考中的 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。

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(..) 時則向前取得:

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 的收件匣

在事件串流上等待新郵件,並在它所在的會話串中回覆:

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 投遞的簽章和時間戳記,並回傳解析後的事件;任何問題都是 Error::WebhookVerification。傳入的請求本文必須與收到時完全一致。標頭可以是 http 的 HeaderMap(如 axum 中那樣)、HashMap,或一串鍵值對:

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 註冊

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

這個呼叫不需要 API 金鑰;回應中帶有新的金鑰和收件匣。未認領的帳號可以做什麼,參閱 Agent 註冊。

这个页面有帮助吗?