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

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

## 安装

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

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

## 发送邮件

```elixir
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 参考](/docs/zh-hans/api-reference)里的 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 区分开。

```elixir
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` 时则向后翻：

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

## Agent 的收件箱

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

```elixir
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](/docs/zh-hans/concepts/webhooks) 投递的签名和时间戳，并返回带有解析后事件的 `{:ok, event}`，或者 `{:error, %BillionSend.WebhookVerificationError{}}`。传入的请求体必须与收到时完全一致，在任何 JSON 解析之前；请求头可以是一个 map，或者像 `conn.req_headers` 这样的键值对列表，名称不区分大小写：

```elixir
# 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`。
