Elixir SDK
Use BillionSend from Elixir with the billionsend Hex package.
The billionsend package is the BillionSend client for Elixir. It covers every operation of the API reference: sending, domains, contacts, broadcasts, templates, webhooks, inboxes with their threads and drafts, live inbox events and agent sign-up. The source is billionsend/billionsend-elixir on GitHub.
Install
Needs Elixir 1.18 or newer and OTP 25 or newer. The package has no dependencies: it uses :httpc and :ssl from OTP and Elixir’s built-in JSON.
def deps do
[{:billionsend, "~> 0.1"}]
end
Send an email
client = BillionSend.client() # reads BILLIONSEND_API_KEY
{:ok, sent} =
BillionSend.Emails.send(
client,
%{
from: "Acme <hello@acme.dev>",
to: ["ana@example.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_...") takes the key directly; base_url:, timeout: (milliseconds per attempt, default 60_000), max_retries:, default_headers: and transport: (a {module, state} implementing BillionSend.Transport, to send through your own HTTP layer) set the rest. BILLIONSEND_BASE_URL overrides the API URL. A client is a plain struct: build it once and pass it to every call, from any process.
Method names
Each operation is a function named after its id in the API reference: the dotted path’s groups make the module and the last segment the function, camelCase written in snake_case. emails.send is BillionSend.Emails.send/3, emails.receiving.attachments.list is BillionSend.Emails.Receiving.Attachments.list/3, and agent.claimEmail is BillionSend.Agent.claim_email/2. emails.metrics is BillionSend.Emails.metrics/2, beside BillionSend.Emails.Metrics.links/2, .countries/2 and .clients/2.
A function takes the client, the path parameters in order, the request body as a map, then a keyword list of options: the query and header parameters (BillionSend.Emails.list(client, limit: 50); a list parameter takes a list), :extra_headers and :timeout, and on the sending functions :idempotency_key. A body the operation does not require may be left out. An unknown option, or a missing required one, raises ArgumentError before anything is sent. Every function returns {:ok, answer} or {:error, error}, and its ! twin (BillionSend.Emails.send!/3) returns the answer or raises. Answers are the API’s JSON decoded into maps with string keys and the API’s own field names (sent["id"]), so the API reference describes them field for field. BillionSend.Client.request(client, "GET", "/path", query: [...]) reaches anything the functions do not cover.
Idempotency and retries
The eight sending functions (Emails.send, Emails.batch, Emails.Receiving.reply and .forward, Inboxes.send, Inboxes.Drafts.send, Inboxes.Threads.Emails.reply and .forward) always send an Idempotency-Key. Without idempotency_key:, each call makes up one (a UUID) that its retries reuse, so a retry after a dropped connection never sends twice; your own key also makes a repeat from another process safe. The same key with a different request is refused with a BillionSend.ConflictError.
Failures worth retrying are retried twice by default: 429, 5xx, no answer (connection failure, timeout), and the 409 concurrent_idempotent_requests answered while the first attempt with the same key is still running. Only requests safe to repeat are retried: GET, PUT, DELETE and any request carrying an idempotency key, as every send does. The client waits as Retry-After asks and returns the error at once when it asks for more than a minute; otherwise it backs off exponentially from 0.5 s to 8 s, with jitter. max_retries: is set on the client (0 turns retries off), and the calling process sleeps between attempts.
Errors
A failed call returns {:error, error} with an exception struct: BillionSend.ValidationError (400, 422), AuthenticationError (401, or no key configured, with name set to missing_api_key before anything is sent), PermissionDeniedError (403), NotFoundError (404), ConflictError (409), RateLimitError (429, with retry_after in seconds), APIError (5xx), APIConnectionError (no answer) or APITimeoutError (the attempt timed out). BillionSend.Error is any other status. Each carries status_code (nil when there was no answer), name (the API’s error name), message and request_id, the answer’s x-request-id, which is the request’s id on the dashboard’s Logs page. BillionSend.Errors.error?/1 tells any of them apart from other terms.
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
Lists
List functions return one page. Every cursor list also has an _all function (search_all for thread search) that returns a lazy Stream, fetching the next pages as it goes, backward when :before is set:
client
|> BillionSend.Contacts.list_all(limit: 100)
|> Enum.each(&IO.puts(&1["email"]))
An agent’s inbox
Wait for new mail on the event stream and reply in its thread:
alias BillionSend.{Inboxes, InboxStreamEvent}
{:ok, events} = Inboxes.Events.stream_inbox(client, "support@acme.dev", types: "inbox.email.received")
events
|> Stream.filter(&match?(%InboxStreamEvent{}, &1)) # a StreamGapEvent: events may be missing, read the threads again
|> 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 opens the stream first, so a refused stream (a revoked key, a key held to one inbox asking for the team’s stream) is an {:error, error} at once; what it returns is a lazy Enumerable of BillionSend.InboxStreamEvent structs (id, event such as "inbox.email.received", and data, the webhook payload’s "type", "created_at", "inbox_id" and "data") and BillionSend.StreamGapEvent structs. The stream reconnects with Last-Event-ID when the connection drops and replays what it missed; keep the id of the last event you handled and pass it back as last_event_id: to resume after a restart. A StreamGapEvent comes once when the stream resumes from more than 24 hours back. max_reconnects: (default 5 failed reconnects in a row) tunes reconnecting, which waits a second, or what the server’s retry field asks, before each attempt; past it the enumeration raises the API’s error for the last attempt, or BillionSend.APIConnectionError when it got no answer. One inbox’s stream ends after that inbox is deleted or expires; BillionSend.Inboxes.Events.stream/2 follows every inbox the key can read. Enumerate a stream once, in the process that opened it: halting the enumeration (Enum.take/2, Stream.take_while/2) closes the connection.
Verify webhooks
BillionSend.verify_webhook/4 checks a webhook delivery’s signature and timestamp with the endpoint’s whsec_ secret and returns {:ok, event} with the parsed event, or {:error, %BillionSend.WebhookVerificationError{}}. Pass the body exactly as it arrived, before any JSON parsing; the headers can be a map or a list of pairs such as conn.req_headers, with names in any case:
# Phoenix: keep the raw body (a Plug.Parsers :body_reader that stores it in 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
A delivery older than five minutes is refused (tolerance:, in seconds, changes that), and during a secret rotation either secret verifies. verify_webhook!/4 returns the event or raises; a secret that is not a whsec_ secret raises ArgumentError.