Ruby-SDK
E-Mails senden, ein Postfach bedienen und Webhooks verifizieren mit dem Gem billionsend: jede API-Operation, Wiederholungsversuche und Idempotenzschlüssel.
Das Gem billionsend ist der BillionSend-Client für Ruby. 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-ruby.
Installation
Erfordert Ruby 3.1 oder neuer. Das Gem hat keine Laufzeit-Abhängigkeiten: Es nutzt net/http, json und openssl aus der Standardbibliothek.
gem install billionsend
In einem Gemfile: gem "billionsend".
E-Mail senden
require "billionsend"
client = BillionSend::Client.new # liest BILLIONSEND_API_KEY
sent = client.emails.send({
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")
puts sent["id"]
BillionSend::Client.new(api_key: "bs_...") nimmt den Schlüssel direkt entgegen. base_url:, timeout: (Sekunden pro Versuch, Standard 60), max_retries:, default_headers: und transport: (alles, was auf call und open_stream antwortet wie BillionSend::NetHTTPTransport, um über Ihren eigenen HTTP-Stack zu senden) legen den Rest fest. BILLIONSEND_BASE_URL überschreibt die API-URL.
Methodennamen
Jede Operation ist eine Methode, benannt nach ihrer ID in der API-Referenz, der durch Punkte getrennte Pfad als Kette von Ressourcen in snake_case: emails.send ist client.emails.send, emails.receiving.attachments.list ist client.emails.receiving.attachments.list, und agent.claimEmail ist client.agent.claim_email. emails.metrics ist client.emails.metrics.call, neben .links, .countries und .clients.
Eine Methode nimmt die Pfadparameter der Reihe nach, den Request-Body als Hash in geschweiften Klammern, dann die Query- und Header-Parameter als Schlüsselwortargumente und zuletzt extra_headers: und timeout:. Bodies nehmen Symbole oder Strings als Schlüssel an. Antworten sind Hashes mit String-Schlüsseln und den Feldnamen der API (sent["id"]), sodass die API-Referenz sie Feld für Feld beschreibt. emails, inboxes und broadcasts haben eine Methode send, die Object#send bei ihnen verdeckt: Rufen Sie ihre Methoden dynamisch mit public_send auf.
Idempotenz und Wiederholungsversuche
Die acht Versand-Operationen (emails.send, emails.batch, Antworten und Weiterleitungen auf empfangene Mails, inboxes.send, inboxes.drafts.send, Thread-Antworten und -Weiterleitungen) senden immer einen Idempotency-Key. Ohne idempotency_key: denkt sich jeder Aufruf einen aus, den seine Wiederholungen weiterverwenden. Ein erneuter Versuch nach einem Timeout sendet also nie doppelt, und Ihr eigener Schlüssel macht auch eine Wiederholung aus einem anderen Prozess sicher.
Fehlschläge, bei denen sich ein neuer Versuch lohnt, werden standardmäßig zweimal wiederholt: 429, 5xx, Timeouts, Netzwerkfehler 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 einem Idempotency-Key, wie ihn jede Versand-Operation trägt. Der Client wartet so lange, wie Retry-After es verlangt, und löst sofort einen Fehler aus, wenn es mehr als eine Minute verlangt. Sonst weicht er exponentiell von 0,5 s bis 8 s zurück, bis zu einem Viertel kürzer nach Zufall. Jede Methode nimmt timeout: und extra_headers: für diesen Aufruf entgegen, die Versand-Methoden zusätzlich idempotency_key:. max_retries: wird am Client gesetzt.
Fehler
Ein fehlgeschlagener Aufruf löst ValidationError (400, 422), AuthenticationError (401 oder kein Schlüssel konfiguriert), 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, eine Art von APIConnectionError) aus. Alle liegen im Modul BillionSend und erweitern BillionSend::Error, das für jeden anderen Status selbst ausgelöst wird, mit status_code, name (dem Fehlernamen der API), message und request_id, dem x-request-id der Antwort, der zugleich die ID der Anfrage auf der Logs-Seite des Dashboards ist.
begin
puts client.emails.get(id)["subject"]
rescue BillionSend::NotFoundError
# no such email
rescue BillionSend::Error => e
warn "#{e.status_code} #{e.name}: #{e.message} (request #{e.request_id})"
end
Listen
Listen-Methoden liefern eine Seite. Jede Cursor-Liste hat außerdem eine Methode ..._all (search_all für die Thread-Suche), die einen trägen Enumerator liefert und die nächsten Seiten nach und nach abruft, rückwärts, wenn before: gesetzt ist:
client.contacts.list_all(limit: 100).each do |contact|
puts contact["email"]
end
Das Postfach eines Agenten
Warten Sie im Ereignis-Stream auf neue Mails und antworten Sie in ihrem Thread:
stream = client.inboxes.events.stream_inbox("support@acme.dev", types: "inbox.email.received")
begin
stream.each do |event|
next if event.is_a?(BillionSend::StreamGapEvent) # Ereignisse können fehlen: Threads erneut lesen
data = event.data["data"]
client.inboxes.threads.emails.reply(
event.data["inbox_id"], data["thread_id"], data["email_id"],
{ text: "Thanks, we are on it." },
idempotency_key: "reply/#{data["email_id"]}"
)
end
ensure
stream.close
end
Der Stream verbindet sich mit Last-Event-ID neu, wenn die Verbindung abbricht, und spielt Verpasstes nach. Behalten Sie stream.last_event_id und übergeben Sie es 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, 0 gibt beim ersten auf) steuert das Wiederverbinden, das vor jedem Versuch eine Sekunde wartet oder so lange, wie das Feld retry des Servers verlangt. Der Stream eines Postfachs endet, nachdem dieses Postfach gelöscht wurde oder abgelaufen ist. client.inboxes.events.stream folgt jedem Postfach, das der Schlüssel lesen kann.
Webhooks verifizieren
BillionSend.verify_webhook prüft Signatur und Zeitstempel einer Webhook-Zustellung mit dem whsec_-Secret des Endpunkts und liefert das geparste Ereignis. Übergeben Sie den Body genau so, wie er angekommen ist. Header-Namen passen unabhängig von der Groß- und Kleinschreibung:
# config.ru
require "billionsend"
SECRET = ENV.fetch("BILLIONSEND_WEBHOOK_SECRET")
NAMES = %w[webhook-id webhook-timestamp webhook-signature].freeze
app = lambda do |env|
headers = NAMES.to_h { |name| [name, env["HTTP_#{name.upcase.tr("-", "_")}"]] }
event = BillionSend.verify_webhook(env["rack.input"].read, headers, SECRET)
warn event["type"]
[204, {}, []]
rescue BillionSend::WebhookVerificationError
[400, {}, ["bad signature"]]
end
run app
Eine Zustellung, die älter als fünf Minuten ist, wird abgelehnt, und während einer Rotation des Secrets verifiziert jedes der beiden Secrets.
Agent-Registrierung
signup = BillionSend::Client.new.agent.signup({ human_email: "owner@acme.dev", name: "Support agent" })
puts signup["inbox"]["email_address"]
Der Aufruf braucht keinen API-Schlüssel. Die Antwort enthält den neuen Schlüssel und das Postfach. Was ein nicht übernommenes Konto darf, steht unter Agent-Registrierung.