Elixir-SDK
E-Mails senden, ein Postfach bedienen und Webhooks verifizieren mit dem Hex-Paket billionsend: jede API-Operation, Wiederholungen und Idempotenzschlüssel.
Das Hex-Paket billionsend ist der BillionSend-Client für Elixir. Es deckt jede Operation der API-Referenz ab: Versand, Domains, Kontakte, Newsletter-Versand, Vorlagen, Webhooks, Postfächer mit ihren Threads und Entwürfen, Live-Ereignisse von Postfächern und die Agent-Registrierung. Der Quellcode liegt auf GitHub unter billionsend/billionsend-elixir.
Installation
Erfordert Elixir 1.18 oder neuer und OTP 25 oder neuer. Das Paket hat keine Abhängigkeiten: Es nutzt :httpc und :ssl aus OTP und das in Elixir eingebaute JSON.
def deps do
[{:billionsend, "~> 0.1"}]
end
E-Mail senden
client = BillionSend.client() # liest 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_...") nimmt den Schlüssel direkt entgegen. base_url:, timeout: (Millisekunden pro Versuch, Standard 60_000), max_retries:, default_headers: und transport: (ein {module, state}, das BillionSend.Transport implementiert, um über Ihre eigene HTTP-Schicht zu senden) legen den Rest fest. BILLIONSEND_BASE_URL überschreibt die API-URL. Ein Client ist eine schlichte Struct: Erzeugen Sie ihn einmal und übergeben Sie ihn an jeden Aufruf, aus jedem Prozess.
Funktionsnamen
Jede Operation ist eine Funktion, benannt nach ihrer ID in der API-Referenz: Die Gruppen des durch Punkte getrennten Pfads bilden das Modul und das letzte Segment die Funktion, camelCase in snake_case geschrieben. emails.send ist BillionSend.Emails.send/3, emails.receiving.attachments.list ist BillionSend.Emails.Receiving.Attachments.list/3, und agent.claimEmail ist BillionSend.Agent.claim_email/2. emails.metrics ist BillionSend.Emails.metrics/2, neben BillionSend.Emails.Metrics.links/2, .countries/2 und .clients/2.
Eine Funktion nimmt den Client, die Pfadparameter der Reihe nach, den Request-Body als Map und dann eine Keyword-Liste mit Optionen: die Query- und Header-Parameter (BillionSend.Emails.list(client, limit: 50); ein Listenparameter nimmt eine Liste), :extra_headers und :timeout, bei den Versand-Funktionen außerdem :idempotency_key. Ein Body, den die Operation nicht verlangt, darf entfallen. Eine unbekannte Option oder eine fehlende Pflichtoption löst ArgumentError aus, bevor etwas gesendet wird. Jede Funktion liefert {:ok, answer} oder {:error, error}, und ihr Gegenstück mit ! (BillionSend.Emails.send!/3) liefert die Antwort oder löst einen Fehler aus. Antworten sind das JSON der API, dekodiert in Maps mit String-Schlüsseln und den Feldnamen der API (sent["id"]), die API-Referenz beschreibt sie also Feld für Feld. Mit BillionSend.Client.request(client, "GET", "/path", query: [...]) erreichen Sie alles, was die Funktionen nicht abdecken.
Idempotenz und Wiederholungsversuche
Die acht Versand-Funktionen (Emails.send, Emails.batch, Emails.Receiving.reply und .forward, Inboxes.send, Inboxes.Drafts.send, Inboxes.Threads.Emails.reply und .forward) senden immer einen Idempotency-Key. Ohne idempotency_key: denkt sich jeder Aufruf einen aus (eine UUID), den seine Wiederholungen weiterverwenden. Ein erneuter Versuch nach einer abgebrochenen Verbindung sendet also nie doppelt, und Ihr eigener Schlüssel macht auch eine Wiederholung aus einem anderen Prozess sicher. Derselbe Schlüssel mit einer anderen Anfrage wird mit einem BillionSend.ConflictError abgelehnt.
Fehlschläge, bei denen sich ein neuer Versuch lohnt, werden standardmäßig zweimal wiederholt: 429, 5xx, keine Antwort (Verbindungsfehler, Timeout) und das 409 concurrent_idempotent_requests, das antwortet, solange der erste Versuch mit demselben Schlüssel noch läuft. Wiederholt werden nur Anfragen, die sich gefahrlos wiederholen lassen: GET, PUT, DELETE und jede Anfrage mit Idempotenzschlüssel, wie sie jeder Versand trägt. Der Client wartet so lange, wie Retry-After es verlangt, und gibt den Fehler sofort zurück, wenn es mehr als eine Minute verlangt. Sonst weicht er exponentiell von 0,5 s bis 8 s zurück, mit Jitter. max_retries: legen Sie am Client fest (0 schaltet Wiederholungen ab), und der aufrufende Prozess schläft zwischen den Versuchen.
Fehler
Ein fehlgeschlagener Aufruf liefert {:error, error} mit einer Exception-Struct: BillionSend.ValidationError (400, 422), AuthenticationError (401 oder kein Schlüssel konfiguriert, dann ist name auf missing_api_key gesetzt, bevor etwas gesendet wird), PermissionDeniedError (403), NotFoundError (404), ConflictError (409), RateLimitError (429, mit retry_after in Sekunden), APIError (5xx), APIConnectionError (keine Antwort) oder APITimeoutError (der Versuch hat das Zeitlimit überschritten). BillionSend.Error ist jeder andere Status. Jede trägt status_code (nil, wenn es keine Antwort gab), name (den Fehlernamen der API), message und request_id, den x-request-id der Antwort, der zugleich die ID der Anfrage auf der Logs-Seite des Dashboards ist. BillionSend.Errors.error?/1 unterscheidet jede von ihnen von anderen Termen.
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
Listen
Listen-Funktionen liefern eine Seite. Jede Cursor-Liste hat außerdem eine Funktion _all (search_all für die Thread-Suche), die einen trägen Stream liefert und die nächsten Seiten nach und nach abruft, rückwärts, wenn :before gesetzt ist:
client
|> BillionSend.Contacts.list_all(limit: 100)
|> Enum.each(&IO.puts(&1["email"]))
Das Postfach eines Agenten
Warten Sie im Ereignis-Stream auf neue Mails und antworten Sie in ihrem 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)) # ein StreamGapEvent: Ereignisse können fehlen, Threads erneut lesen
|> 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 öffnet den Stream zuerst, ein abgelehnter Stream (ein widerrufener Schlüssel, ein auf ein Postfach beschränkter Schlüssel, der den Stream des Teams verlangt) ist also sofort ein {:error, error}. Zurück kommt ein träges Enumerable aus BillionSend.InboxStreamEvent-Structs (id, event, etwa "inbox.email.received", und data, also "type", "created_at", "inbox_id" und "data" der Webhook-Nutzdaten) und BillionSend.StreamGapEvent-Structs. Der Stream verbindet sich mit Last-Event-ID neu, wenn die Verbindung abbricht, und spielt Verpasstes nach. Behalten Sie die id des letzten Ereignisses, das Sie verarbeitet haben, und übergeben Sie sie als last_event_id: zurück, um nach einem Neustart fortzusetzen. Ein StreamGapEvent kommt einmal, wenn der Stream von weiter als 24 Stunden zurück fortgesetzt wird. max_reconnects: (Standard 5 fehlgeschlagene Wiederverbindungen in Folge) steuert das Wiederverbinden, das vor jedem Versuch eine Sekunde wartet oder so lange, wie das Feld retry des Servers verlangt. Danach löst die Enumeration den Fehler der API für den letzten Versuch aus, oder BillionSend.APIConnectionError, wenn sie keine Antwort bekam. Der Stream eines Postfachs endet, nachdem dieses Postfach gelöscht wurde oder abgelaufen ist. BillionSend.Inboxes.Events.stream/2 folgt jedem Postfach, das der Schlüssel lesen kann. Enumerieren Sie einen Stream nur einmal, in dem Prozess, der ihn geöffnet hat: Bricht man die Enumeration ab (Enum.take/2, Stream.take_while/2), schließt das die Verbindung.
Webhooks verifizieren
BillionSend.verify_webhook/4 prüft Signatur und Zeitstempel einer Webhook-Zustellung mit dem whsec_-Secret des Endpunkts und liefert {:ok, event} mit dem geparsten Ereignis oder {:error, %BillionSend.WebhookVerificationError{}}. Übergeben Sie den Body genau so, wie er angekommen ist, vor jedem JSON-Parsen. Die Header können eine Map oder eine Liste von Paaren sein, etwa conn.req_headers, mit Namen in jeder Schreibweise:
# Phoenix: den Roh-Body aufbewahren (ein Plug.Parsers-:body_reader, der ihn in conn.assigns ablegt)
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
Eine Zustellung, die älter als fünf Minuten ist, wird abgelehnt (tolerance: in Sekunden ändert das), und während einer Rotation des Secrets verifiziert jedes der beiden Secrets. verify_webhook!/4 liefert das Ereignis oder löst einen Fehler aus. Ein Secret, das kein whsec_-Secret ist, löst ArgumentError aus.