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

Elixir SDK

用 billionsend Hex 包在 Elixir 里发送邮件、使用收件箱、验证 Webhook,覆盖全部 API 操作,内置重试与幂等键。

billionsend 包是 BillionSend 面向 Elixir 的客户端。它覆盖 API 参考里的全部操作:发送、域名、联系人、群发、模板、Webhook、带会话和草稿的收件箱、实时的收件箱事件,以及 Agent 注册。源码在 GitHub 上的 billionsend/billionsend-elixir。

安装

需要 Elixir 1.18 或更高版本,以及 OTP 25 或更高版本。这个包没有依赖:它使用 OTP 的 :httpc 和 :ssl,以及 Elixir 内置的 JSON。

def deps do
  [{:billionsend, "~> 0.1"}]
end

发送邮件

client = BillionSend.client()  # 读取 BILLIONSEND_API_KEY

{:ok, sent} =
  BillionSend.Emails.send(
    client,
    %{
      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"
  )

IO.puts(sent["id"])

BillionSend.client(api_key: "bs_...") 直接传入密钥;base_url:、timeout:(每次尝试的毫秒数,默认 60_000)、max_retries:、default_headers: 和 transport:(一个实现了 BillionSend.Transport 的 {module, state},用来通过你自己的 HTTP 层发送)设置其余选项。BILLIONSEND_BASE_URL 可以覆盖 API 地址。客户端就是一个普通的 struct:创建一次,然后在任何进程里把它传给每个调用。

方法命名

每个操作都是一个函数,名字取自它在 API 参考里的 id:用点分隔的路径中,前面的各组组成模块,最后一段是函数名,camelCase 写成 snake_case。emails.send 是 BillionSend.Emails.send/3,emails.receiving.attachments.list 是 BillionSend.Emails.Receiving.Attachments.list/3,agent.claimEmail 是 BillionSend.Agent.claim_email/2。emails.metrics 是 BillionSend.Emails.metrics/2,旁边还有 BillionSend.Emails.Metrics.links/2、.countries/2 和 .clients/2。

一个函数依次接收:客户端、路径参数(按顺序)、作为 map 的请求体,然后是一个选项关键字列表:查询参数和请求头参数(BillionSend.Emails.list(client, limit: 50);列表参数传入一个列表)、:extra_headers 和 :timeout,发送类函数还有 :idempotency_key。操作不要求的请求体可以省略。传入未知的选项,或者缺少必填的选项,会在发出任何请求之前抛出 ArgumentError。每个函数都返回 {:ok, answer} 或 {:error, error},对应带 ! 的版本(BillionSend.Emails.send!/3)则返回响应,或者抛出异常。响应是 API 返回的 JSON 解码成的 map,键是字符串,字段名就是 API 自己的字段名(sent["id"]),所以 API 参考里的说明可以逐字段对应。BillionSend.Client.request(client, "GET", "/path", query: [...]) 可以访问这些函数没有覆盖的任何接口。

幂等与重试

八个发送函数(Emails.send、Emails.batch、Emails.Receiving.reply 与 .forward、Inboxes.send、Inboxes.Drafts.send、Inboxes.Threads.Emails.reply 与 .forward)总是会带上 Idempotency-Key。如果没有 idempotency_key:,每次调用会自己生成一个(UUID),它的重试沿用这个密钥,所以连接中断后的重试不会重复发送;你自己的密钥还能让另一个进程里的重复调用也保持安全。同一个密钥搭配不同的请求会被拒绝,返回 BillionSend.ConflictError。

值得重试的失败默认会重试两次:429、5xx、没有响应(连接失败、超时),以及同一个密钥的第一次请求仍在运行时返回的 409 concurrent_idempotent_requests。只有可以安全重复的请求才会重试:GET、PUT、DELETE,以及任何带幂等键的请求(每次发送都带)。客户端按 Retry-After 的要求等待,要求等待超过一分钟时直接返回错误;其余情况从 0.5 s 起按指数退避,最多 8 s,并带有随机抖动。max_retries: 在客户端上设置(0 表示关闭重试),调用方进程会在两次尝试之间休眠。

错误

失败的调用会返回 {:error, error},其中 error 是一个异常 struct:BillionSend.ValidationError(400、422)、AuthenticationError(401,或没有配置密钥,此时在发出任何请求之前就会返回,name 为 missing_api_key)、PermissionDeniedError(403)、NotFoundError(404)、ConflictError(409)、RateLimitError(429,retry_after 以秒为单位)、APIError(5xx)、APIConnectionError(没有响应)或 APITimeoutError(这次尝试超时)。其余任何状态码对应的是 BillionSend.Error。每个都带 status_code(没有响应时为 nil)、name(API 的错误名)、message 和 request_id;request_id 是响应的 x-request-id,也就是这个请求在控制台日志页面上的 id。BillionSend.Errors.error?/1 可以把它们中的任何一个与其它 term 区分开。

case BillionSend.Emails.get(client, id) do
  {:ok, email} -> email["subject"]
  {:error, %BillionSend.NotFoundError{}} -> nil
  {:error, %BillionSend.RateLimitError{retry_after: seconds}} -> {:retry_in, seconds}
  {:error, error} -> Logger.error("#{error.status_code} #{error.name}: #{error.message} (request #{error.request_id})")
end

列表

列表函数返回一页。每个游标列表还有一个 _all 函数(会话搜索是 search_all),返回一个惰性的 Stream,会在迭代的过程中获取后续的页;设置了 :before 时则向后翻:

client
|> BillionSend.Contacts.list_all(limit: 100)
|> Enum.each(&IO.puts(&1["email"]))

Agent 的收件箱

在事件流上等待新邮件,并在它所在的会话里回复:

alias BillionSend.{Inboxes, InboxStreamEvent}

{:ok, events} = Inboxes.Events.stream_inbox(client, "support@acme.dev", types: "inbox.email.received")

events
|> Stream.filter(&match?(%InboxStreamEvent{}, &1))  # 即 StreamGapEvent:事件可能有缺失,重新读取会话
|> Enum.each(fn %InboxStreamEvent{data: %{"inbox_id" => inbox_id, "data" => data}} ->
  %{"thread_id" => thread_id, "email_id" => email_id} = data

  Inboxes.Threads.Emails.reply(
    client,
    inbox_id,
    thread_id,
    email_id,
    %{text: "Thanks, we are on it."},
    idempotency_key: "reply/#{email_id}"
  )
end)

stream_inbox/3 会先打开事件流,所以被拒绝的事件流(密钥已被撤销,或者只限定一个收件箱的密钥请求整个团队的事件流)会立刻返回 {:error, error};它返回的是一个惰性的 Enumerable,里面是 BillionSend.InboxStreamEvent struct(id,event,例如 "inbox.email.received",以及 data,即 Webhook 负载里的 "type"、"created_at"、"inbox_id" 和 "data")和 BillionSend.StreamGapEvent struct。连接断开时,事件流会带着 Last-Event-ID 重新连接,并补上错过的事件;保存你处理的最后一个事件的 id,再把它作为 last_event_id: 传回去,就能在重启之后继续。从 24 小时之前的位置恢复时,会收到一次 StreamGapEvent。max_reconnects:(默认连续失败 5 次重连)用来调整重连行为,每次尝试之前会等待一秒,或者服务器的 retry 字段要求的时间;超过这个次数后,枚举会抛出最后一次尝试时 API 返回的错误,如果没有得到响应,则抛出 BillionSend.APIConnectionError。单个收件箱的事件流在该收件箱被删除或过期后结束;BillionSend.Inboxes.Events.stream/2 会跟随这把密钥能读取的所有收件箱。一个事件流只能在打开它的进程里枚举一次:中途停止枚举(Enum.take/2、Stream.take_while/2)会关闭连接。

验证 Webhook

BillionSend.verify_webhook/4 用端点的 whsec_ 密钥检查一次 Webhook 投递的签名和时间戳,并返回带有解析后事件的 {:ok, event},或者 {:error, %BillionSend.WebhookVerificationError{}}。传入的请求体必须与收到时完全一致,在任何 JSON 解析之前;请求头可以是一个 map,或者像 conn.req_headers 这样的键值对列表,名称不区分大小写:

# Phoenix:保留原始请求体(用 Plug.Parsers 的 :body_reader 把它存进 conn.assigns)
def create(conn, _params) do
  case BillionSend.verify_webhook(conn.assigns.raw_body, conn.req_headers, webhook_secret()) do
    {:ok, %{"type" => "email.bounced", "data" => %{"email_id" => id}}} ->
      mark_bounced(id)
      send_resp(conn, 204, "")

    {:ok, _event} ->
      send_resp(conn, 204, "")

    {:error, %BillionSend.WebhookVerificationError{}} ->
      send_resp(conn, 400, "")
  end
end

超过五分钟的投递会被拒绝(以秒为单位的 tolerance: 可以改变这一点),密钥轮换期间,新旧两个密钥都能通过验证。verify_webhook!/4 返回事件,或者抛出异常;不是 whsec_ 密钥的密钥会抛出 ArgumentError。

这个页面有帮助吗?