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

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

## 安装

需要 Ruby 3.1 或更高版本。这个 gem 没有运行时依赖：它使用标准库里的 `net/http`、`json` 和 `openssl`。

```sh
gem install billionsend
```

在 Gemfile 里写 `gem "billionsend"`。

## 发送邮件

```ruby
require "billionsend"

client = BillionSend::Client.new # 读取 BILLIONSEND_API_KEY

sent = client.emails.send({
  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")

puts sent["id"]
```

`BillionSend::Client.new(api_key: "bs_...")` 直接传入密钥；`base_url:`、`timeout:`（每次尝试的秒数，默认 60）、`max_retries:`、`default_headers:` 和 `transport:`（任何像 `BillionSend::NetHTTPTransport` 那样响应 `call` 和 `open_stream` 的对象，用来通过你自己的 HTTP 栈发送）设置其余选项。`BILLIONSEND_BASE_URL` 可以覆盖 API 地址。

## 方法命名

每个操作都是一个方法，名字取自它在 [API 参考](/docs/zh-hans/api-reference)里的 id，用点分隔的路径变成一串 snake_case 的资源：`emails.send` 是 `client.emails.send`，`emails.receiving.attachments.list` 是 `client.emails.receiving.attachments.list`，`agent.claimEmail` 是 `client.agent.claim_email`。`emails.metrics` 是 `client.emails.metrics.call`，旁边还有 `.links`、`.countries` 和 `.clients`。

一个方法依次接收：路径参数（按顺序）、花括号里作为 Hash 的请求体，然后是作为关键字参数的查询和请求头参数，最后是 `extra_headers:` 和 `timeout:`。请求体的键可以是符号或字符串；响应是以字符串为键的 Hash，字段名就是 API 自己的字段名（`sent["id"]`），所以 API 参考里的说明可以逐字段对应。`emails`、`inboxes` 和 `broadcasts` 有一个 `send` 方法，它遮住了这些对象上的 `Object#send`：要动态调用它们的方法，请用 `public_send`。

## 幂等与重试

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

值得重试的失败默认会重试两次：429、5xx、超时、网络错误，以及同一个密钥的第一次请求仍在运行时返回的 `409 concurrent_idempotent_requests`。只有可以安全重复的请求才会重试：`GET`、`PUT`、`DELETE`，以及任何带 `Idempotency-Key` 的请求，每个发送操作都是如此。客户端按 `Retry-After` 的要求等待，要求等待超过一分钟时立刻抛出；其余情况从 0.5 s 起按指数退避，最多 8 s，并随机减少最多四分之一。每个方法都接受用于该次调用的 `timeout:` 和 `extra_headers:`，发送类方法还接受 `idempotency_key:`；`max_retries:` 在客户端上设置。

## 错误

失败的调用会抛出 `ValidationError`（400、422）、`AuthenticationError`（401，或没有配置密钥）、`PermissionDeniedError`（403）、`NotFoundError`（404）、`ConflictError`（409）、`RateLimitError`（429，`retry_after` 以秒为单位）、`APIError`（5xx）、`APIConnectionError`（没有响应）或 `APITimeoutError`（这次尝试超时，属于 `APIConnectionError` 的一种）。它们都在 `BillionSend` 模块里，并继承自 `BillionSend::Error`，其他任何状态则直接抛出 `BillionSend::Error` 本身；每个错误都带 `status_code`、`name`（API 的错误名）、`message` 和 `request_id`；`request_id` 是响应的 `x-request-id`，也就是这个请求在控制台日志页面上的 id。

```ruby
begin
  puts client.emails.get(id)["subject"]
rescue BillionSend::NotFoundError
  # 没有这封邮件
rescue BillionSend::Error => e
  warn "#{e.status_code} #{e.name}: #{e.message} (request #{e.request_id})"
end
```

## 列表

列表方法返回一页。每个游标列表还有一个 `..._all` 方法（会话搜索是 `search_all`），返回一个惰性的 `Enumerator`，在迭代过程中获取后续的页；设置了 `before:` 时则向后翻：

```ruby
client.contacts.list_all(limit: 100).each do |contact|
  puts contact["email"]
end
```

## Agent 的收件箱

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

```ruby
stream = client.inboxes.events.stream_inbox("support@acme.dev", types: "inbox.email.received")
begin
  stream.each do |event|
    next if event.is_a?(BillionSend::StreamGapEvent) # 事件可能有缺失：重新读取会话

    data = event.data["data"]
    client.inboxes.threads.emails.reply(
      event.data["inbox_id"], data["thread_id"], data["email_id"],
      { text: "Thanks, we are on it." },
      idempotency_key: "reply/#{data["email_id"]}"
    )
  end
ensure
  stream.close
end
```

连接断开时，事件流会带着 `Last-Event-ID` 重新连接，并补上错过的事件；保存 `stream.last_event_id`，再用 `last_event_id:` 传回去，就能在重启之后继续。从 24 小时之前的位置恢复时，会收到一次 `StreamGapEvent`。`max_reconnects:`（默认连续失败 5 次重连；`0` 表示第一次失败就放弃）用来调整重连行为，每次尝试之前会等待一秒，或者服务器的 `retry` 字段要求的时间。单个收件箱的事件流在该收件箱被删除或过期后结束；`client.inboxes.events.stream` 会跟随这把密钥能读取的所有收件箱。

## 验证 Webhook

`BillionSend.verify_webhook` 用端点的 `whsec_` 密钥检查一次 [Webhook](/docs/zh-hans/concepts/webhooks) 投递的签名和时间戳，并返回解析后的事件。传入的请求体必须与收到时完全一致；请求头名称不区分大小写：

```ruby
# config.ru
require "billionsend"

SECRET = ENV.fetch("BILLIONSEND_WEBHOOK_SECRET")
NAMES = %w[webhook-id webhook-timestamp webhook-signature].freeze

app = lambda do |env|
  headers = NAMES.to_h { |name| [name, env["HTTP_#{name.upcase.tr("-", "_")}"]] }
  event = BillionSend.verify_webhook(env["rack.input"].read, headers, SECRET)
  warn event["type"]
  [204, {}, []]
rescue BillionSend::WebhookVerificationError
  [400, {}, ["bad signature"]]
end

run app
```

超过五分钟的投递会被拒绝，密钥轮换期间，新旧两个密钥都能通过验证。

## Agent 注册

```ruby
signup = BillionSend::Client.new.agent.signup({ human_email: "owner@acme.dev", name: "Support agent" })
puts signup["inbox"]["email_address"]
```

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