跳到内容
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 s)、.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 自己的字段名。它返回一个请求构建器,查询和请求头参数就是它的设置方法(.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。

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 注册。

这个页面有帮助吗?