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

Elixir SDK

用 billionsend Hex 套件在 Elixir 中使用 BillionSend。

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 表示的請求本文,然後是一個選項 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 區分開來。

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,也可以是由成對項目組成的 list(例如 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。

这个页面有帮助吗?