---
title: Elixir SDK
description: 用 billionsend Hex 套件在 Elixir 中使用 BillionSend。
ai:
  exclude: true
---

`billionsend` 套件是 BillionSend 面向 Elixir 的用戶端。它涵蓋 [API 參考](/docs/zh-hant/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-hant/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 表示的請求本文，然後是一個選項 keyword list：查詢與標頭參數（`BillionSend.Emails.list(client, limit: 50)`；清單參數接受一個 list）、`: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 秒到 8 秒採指數退避，並加上抖動。`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-hant/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-hant/concepts/webhooks) 投遞的簽章和時間戳記，並回傳含有解析後事件的 `{:ok, event}`，否則回傳 `{:error, %BillionSend.WebhookVerificationError{}}`。傳入原樣的請求本文，在任何 JSON 解析之前；標頭可以是 map，也可以是由成對項目組成的 list（例如 `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`。
