Ruby SDK
用 billionsend gem 在 Ruby 里发送邮件、使用收件箱、验证 Webhook,覆盖全部 API 操作,内置重试与幂等键。
billionsend gem 是 BillionSend 面向 Ruby 的客户端。它覆盖 API 参考里的全部操作:发送、域名、联系人、群发、模板、Webhook、带会话和草稿的收件箱、实时的收件箱事件,以及 Agent 注册。源码在 GitHub 上的 billionsend/billionsend-ruby。
安装
需要 Ruby 3.1 或更高版本。这个 gem 没有运行时依赖:它使用标准库里的 net/http、json 和 openssl。
gem install billionsend
在 Gemfile 里写 gem "billionsend"。
发送邮件
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 参考里的 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。
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: 时则向后翻:
client.contacts.list_all(limit: 100).each do |contact|
puts contact["email"]
end
Agent 的收件箱
在事件流上等待新邮件,并在它所在的会话里回复:
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 投递的签名和时间戳,并返回解析后的事件。传入的请求体必须与收到时完全一致;请求头名称不区分大小写:
# 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 注册
signup = BillionSend::Client.new.agent.signup({ human_email: "owner@acme.dev", name: "Support agent" })
puts signup["inbox"]["email_address"]
这个调用不需要 API 密钥;响应里带有新的密钥和收件箱。未认领的账号可以做什么,见 Agent 注册。