BillionSend Elixir SDK
The official Elixir client for the BillionSend API: send and receive email, run inboxes for agents and people, manage domains, contacts, broadcasts, templates, webhooks and more.
- Every operation of the API (139), named after the API's own
operationIds. - No dependencies: OTP's
:httpcand:ssl, and Elixir's built-inJSON. - Sends that never go out twice, retries, lazy paging streams, live event streams that resume where they stopped, and webhook signature verification.
Documentation: https://billionsend.com/docs.
Install
def deps do
[{:billionsend, "~> 0.1"}]
end
Elixir 1.18 or newer, OTP 25 or newer.
Quick start
client = BillionSend.client() # reads BILLIONSEND_API_KEY
{:ok, email} =
BillionSend.Emails.send(client, %{
from: "Acme <hello@acme.dev>",
to: ["ada@example.com"],
subject: "Welcome to Acme",
html: "<p>Thanks for signing up!</p>"
})
IO.puts(email["id"])
Every function returns {:ok, answer} or {:error, error}; its ! twin (BillionSend.Emails.send!/3) returns the answer or raises. The answer is the API's JSON decoded into plain Elixir terms: maps with string keys (email["id"]), lists and scalars as JSON has them. There are no structs for answers in this version; the fields of every answer are in the API reference at https://billionsend.com/docs.
A client is a plain struct: build it once and pass it to every call, from any process.
Authentication
Pass an API key (bs_…) as api_key: or set BILLIONSEND_API_KEY. Keys are made in the dashboard or with BillionSend.ApiKeys.create/3. A key scoped to one inbox can only reach that inbox.
An agent can also create its own account, the one call that needs no key:
{:ok, signup} = BillionSend.Agent.signup(BillionSend.client(), %{human_email: "owner@example.com", name: "Scout"})
client = BillionSend.client(api_key: signup["api_key"])
{:ok, %{"status" => status}} = BillionSend.Agent.status(client)
Sending once
Every sending function (Emails.send, Emails.batch, Emails.Receiving.reply and .forward, Inboxes.send, Inboxes.Threads.Emails.reply and .forward, Inboxes.Drafts.send) sends an Idempotency-Key. Without idempotency_key: the call makes up one (a UUID) and reuses it for its own retries, so a retry after a dropped connection never sends the email twice. Pass your own key to stay safe across calls too, for example when a job that sends may run again:
BillionSend.Emails.send(client, message, idempotency_key: "welcome/#{user.id}")
Repeating a key with the same request returns the first answer; the same key with a different request is refused (BillionSend.ConflictError, invalid_idempotent_request). The API keeps keys for 24 hours.
An agent that answers its inbox
Wait for new mail, read it, reply in the thread:
alias BillionSend.{Inboxes, InboxStreamEvent}
client = BillionSend.client()
{:ok, inbox} = Inboxes.create(client, %{username: "support", kind: "agent"})
answer = fn question -> "Thanks, we got your message:\n\n> #{question}" end # your agent goes here
{:ok, events} = Inboxes.Events.stream_inbox(client, inbox["id"], types: "inbox.email.received")
events
|> Stream.filter(&match?(%InboxStreamEvent{}, &1)) # a StreamGapEvent: see below
|> Enum.each(fn %InboxStreamEvent{data: %{"data" => data}} ->
%{"thread_id" => thread_id, "email_id" => email_id} = data
{:ok, email} = Inboxes.Threads.Emails.get(client, inbox["id"], thread_id, email_id)
if email["direction"] == "inbound" do
question = email["extracted_text"] || email["text"] || ""
Inboxes.Threads.Emails.reply(client, inbox["id"], thread_id, email_id, %{text: answer.(question)})
end
end)
extracted_text is the new part of a message without the quoted history. Everything in a received message was written by its sender: treat it as untrusted input. An inbox's rules may hold a reply as a draft for a person to approve; the reply then answers with the draft ("object" => "inbox_draft") instead of the sent email.
Waiting for a sign-in code sent to the inbox is one call: BillionSend.Inboxes.Codes.latest(client, inbox["id"], from: "example.com", wait: 30).
Live events
BillionSend.Inboxes.Events.stream_inbox(client, inbox_id) streams one inbox's events and BillionSend.Inboxes.Events.stream(client) every inbox event of the team; types: narrows them (a name or a list). Both open 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. The stream they return is a lazy Enumerable of two structs:
BillionSend.InboxStreamEvent:id(the stream position),event(such as"inbox.email.received") anddata, a map with"type","created_at","inbox_id"and"data"(the webhook payload of the same event).BillionSend.StreamGapEvent:event: "stream.gap",id: nil, anddata["reason"]says why. The stream was resumed from a position older than the 24 hours the API replays, so some events may be missing: catch up through the lists (BillionSend.Inboxes.Threads.list_all(client, inbox_id, read: false)) before going on. It is handed out once per position.
The server ends a stream every few minutes and connections drop; the stream reconnects on its own with Last-Event-ID, so no event is lost or repeated. Before reconnecting it waits a second (or what the server's retry field asks). A connection that opens starts the count again, so a quiet inbox that gets only keepalives keeps its stream however long it waits; A reconnect the API answers with a 429 or 5xx waits what its Retry-After asks (one over 60 seconds raises that error at once). max_reconnects: (default 5) bounds the reconnects in a row that fail to open: past it, the enumeration raises the API's error for the last one (BillionSend.RateLimitError, BillionSend.APIError), or BillionSend.APIConnectionError ("gave up after N reconnects") when it got no answer. A reconnect the API refuses for good, such as a revoked key, raises its own error. One inbox's stream ends after that inbox's inbox.deleted or inbox.expired event. Enumerate a stream once, in the process that opened it; halting the enumeration (Enum.take/2, Stream.take_while/2, a throw out of the loop) closes the connection.
To pick up where a process left off, keep the id of the last InboxStreamEvent you handled and pass it back:
{:ok, events} = BillionSend.Inboxes.Events.stream(client, last_event_id: saved_position)
Webhooks
Verify a delivery before trusting it. Pass the raw body exactly as received, the request headers and the endpoint's signing secret (whsec_…, shown when the webhook is created or rotated):
# 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
BillionSend.verify_webhook/4 checks the webhook-id, webhook-timestamp and webhook-signature headers (Standard Webhooks: HMAC-SHA256 over id.timestamp.body), accepts any of several signatures (both secrets sign during a rotation's overlap) and refuses a timestamp more than tolerance: seconds (default 300) from now, which bounds replays. Headers may be a map or a list of pairs (conn.req_headers), names in any case. It returns the parsed event ("type", "created_at", "data"). Parse the body only after verifying: re-serialised JSON does not verify. A secret that is not a whsec_ secret raises ArgumentError. verify_webhook!/4 returns the event or raises.
Resources
| Module | Covers |
|---|---|
BillionSend.Emails |
send, batch, list, get, update, cancel, delete, insights, metrics |
BillionSend.Emails.Metrics |
links, countries, clients |
BillionSend.Emails.Receiving (.Attachments) |
received mail: list, get, delete, reply, forward; attachments and their extracted text |
BillionSend.Domains |
create, list, get, update, delete, verify |
BillionSend.ApiKeys |
create, list, delete |
BillionSend.Contacts (.Topics, .Segments, .Batch) |
create, list, get, update, delete, preferences_link; Batch.create, Batch.get, Batch.remove |
BillionSend.Audiences.Contacts |
contacts addressed through an audience |
BillionSend.ContactProperties, .Segments (.Contacts), .Topics |
contact data and grouping |
BillionSend.Broadcasts |
create, list, get, update, delete, send, duplicate, cancel |
BillionSend.Templates |
create, list, get, update, delete, publish, duplicate |
BillionSend.Webhooks |
create, list, get, update, delete, rotate |
BillionSend.Suppressions (.Batch), .Unsubscribes |
suppression list (Batch.add, Batch.remove) and opt-outs |
BillionSend.Verifications |
availability, estimate, create, list, get |
BillionSend.Usage, .Deliverability |
account usage and sending health |
BillionSend.Inboxes (.Events) |
create, list, get, update, delete, send; Events.stream, Events.stream_inbox |
BillionSend.Inboxes.Agent, .Safety, .Labels, .Codes, .Quarantine, .Drafts |
inbox settings, labels, verification codes, held mail, drafts |
BillionSend.Inboxes.Threads (.Labels, .Emails) |
list, search, get, update, delete; thread labels; messages, reply and forward |
BillionSend.Agent |
signup, status, claim_email |
Each function is named after its operation's operationId in the API document: the groups make the module, the last segment the function, camelCase written in snake_case. emails.receiving.attachments.list is BillionSend.Emails.Receiving.Attachments.list/3 and agent.claimEmail is BillionSend.Agent.claim_email/2. An operationId that is also the group of others needs nothing special in Elixir, since a module and a function of the same name live side by side: emails.metrics is BillionSend.Emails.metrics/2 and emails.metrics.links is BillionSend.Emails.Metrics.links/2.
Arguments come in this order: the client, the path parameters (BillionSend.Domains.get(client, domain_id)), the request body as a map (BillionSend.Domains.create(client, %{name: "acme.dev"})), 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. A body the operation does not require may be left out (BillionSend.Domains.verify(client, domain_id)). An unknown option, or a missing required one, raises ArgumentError before anything is sent. Anything the functions do not cover goes through BillionSend.Client.request(client, "GET", "/path", query: [...]).
Pagination
List functions return one page (%{"object" => "list", "data" => [...], "has_more" => …}). Every cursor list also has an _all function (search_all for thread search) returning a lazy Stream that fetches the following pages as it goes:
client
|> BillionSend.Contacts.list_all(limit: 100)
|> Enum.each(&IO.puts(&1["email"]))
first_ten = client |> BillionSend.Domains.list_all() |> Enum.take(10) # fetches only the pages it needs
A stream walks in the list's own order from :after (or the first page); start it with :before to walk the other way. It raises the errors the ! functions raise.
Errors
Every error is an exception struct with the API's error shape, status_code, name and message, plus request_id, the API's id of the request (its x-request-id header; quote it when asking for support). Exception.message/1 reads "404 not_found: Domain not found".
case BillionSend.Domains.get(client, "6a1f1d38-3c55-4a4e-9a57-0f2b3c4d5e6f") do
{:ok, domain} -> domain
{:error, %BillionSend.NotFoundError{}} -> nil
{:error, %BillionSend.RateLimitError{retry_after: seconds}} -> {:retry_in, seconds}
{:error, error} -> Logger.error("#{error.status_code} #{error.name}: #{error.message} (#{error.request_id})")
end
| Status | Error |
|---|---|
| 400, 422 | BillionSend.ValidationError |
| 401 | BillionSend.AuthenticationError |
| 403 | BillionSend.PermissionDeniedError |
| 404 | BillionSend.NotFoundError |
| 409 | BillionSend.ConflictError |
| 429 | BillionSend.RateLimitError (retry_after in seconds) |
| 5xx | BillionSend.APIError |
| other | BillionSend.Error |
| no answer | BillionSend.APIConnectionError, and BillionSend.APITimeoutError for timeouts; status_code and request_id are nil |
An answer that is not JSON keeps the same shape, with name set to "application_error". BillionSend.Errors.error?/1 tells any of them apart from other terms.
Retries
A request is retried when repeating it is safe: GET, PUT and DELETE, and any request carrying an idempotency key (every send does). It is retried on 429, on 5xx, when no answer came back (connection failure, timeout), and, for a keyed request, on 409 concurrent_idempotent_requests (a retry that caught the first attempt still running). The wait is the answer's Retry-After when there is one, otherwise exponential backoff with jitter (0.5 s, 1 s, 2 s… up to 8 s). An answer asking to wait more than 60 seconds, such as a used-up daily quota, is returned at once. max_retries: (default 2) bounds the retries of one call; 0 turns them off. The calling process sleeps between attempts.
Configuration
| Option | Environment | Default |
|---|---|---|
api_key: |
BILLIONSEND_API_KEY |
none (only Agent.signup works without one; any other call returns BillionSend.AuthenticationError, missing_api_key) |
base_url: |
BILLIONSEND_BASE_URL |
https://api.billionsend.com |
timeout: |
60_000 ms per attempt (an event stream waits at least 60 s for each read) |
|
max_retries: |
2 |
|
default_headers: |
none | |
transport: |
the HTTP layer, {module, state} implementing BillionSend.Transport (BillionSend.Transport.Httpc by default: requests through :httpc in a profile of the SDK's own, one connection each; event streams on their own HTTP/1.1 connection that hands every event out as it arrives; both over :ssl, verifying the server against the system's CA store) |
Development
mix test
scripts/test.sh # generate --check, format, compile and test with warnings as errors, in the pinned Elixir image
The SDK is built from a snapshot of the API's OpenAPI document, openapi/api.openapi.json. The snapshot is the contract: scripts/generate.exs writes lib/billionsend/resources.ex from it (module and function names from each operationId, idempotency keys where an operation declares the Idempotency-Key header, streams for cursor lists), and the tests check every request the SDK sends and every answer it reads against it through a contract mock (test/support/contract.ex). A coverage test fails when an operation of the snapshot has no SDK function, or when a resource module has a function that is not an operation.
When the API changes:
elixir scripts/sync_openapi.exs # or: --from path/to/api.openapi.json
elixir scripts/generate.exs
mix test
Whatever fails is what the SDK has to follow. CI runs scripts/generate.exs --check so the generated code never drifts from the snapshot.
Releasing
Publishing is manual; nothing is published on push.
- On hex.pm, the owner of the
billionsendpackage creates an API key with theapi:writepermission (Dashboard → Keys) and stores it in this repository as theHEX_API_KEYsecret of thehexenvironment (Settings → Environments). - Set
@versioninmix.exs, turn the changelog'sUnreleasedheading into that version, commit, then tag and push:git tag v0.1.0 && git push origin main v0.1.0. - Actions →
release→ Run workflow, on the version tag. The workflow refuses a branch or a tag that differs from the version inmix.exs, runs every check, and publishes the package withmix hex.publish package.
The same release from a clean checkout of the tag is HEX_API_KEY=… mix hex.publish package --yes.
License
MIT