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