SDK Ruby
Envoyez des e-mails, gérez une boîte de réception, vérifiez des webhooks en Ruby avec la gem billionsend : toute l'API, nouvelles tentatives, idempotence.
La gem billionsend est le client BillionSend pour Ruby. Elle couvre toutes les opérations de la référence de l’API : envoi, domaines, contacts, campagnes, templates, webhooks, boîtes de réception avec leurs fils de discussion et leurs brouillons, événements de boîte de réception en direct et inscription des agents. Le code source est sur GitHub : billionsend/billionsend-ruby.
Installer
Nécessite Ruby 3.1 ou plus récent. La gem n’a aucune dépendance d’exécution : elle utilise net/http, json et openssl de la bibliothèque standard.
gem install billionsend
Dans un Gemfile, gem "billionsend".
Envoyer un e-mail
require "billionsend"
client = BillionSend::Client.new # reads 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_...") prend la clé directement ; base_url:, timeout: (en secondes par tentative, 60 par défaut), max_retries:, default_headers: et transport: (tout objet qui répond à call et open_stream comme BillionSend::NetHTTPTransport, pour envoyer par votre propre pile HTTP) règlent le reste. BILLIONSEND_BASE_URL remplace l’URL de l’API.
Noms des méthodes
Chaque opération est une méthode qui porte le nom de son identifiant dans la référence de l’API, le chemin séparé par des points devenant une chaîne de ressources en snake_case : emails.send devient client.emails.send, emails.receiving.attachments.list devient client.emails.receiving.attachments.list, et agent.claimEmail devient client.agent.claim_email. emails.metrics devient client.emails.metrics.call, à côté de .links, .countries et .clients.
Une méthode prend, dans l’ordre, les paramètres de chemin, le corps de la requête sous forme de Hash entre accolades, puis les paramètres de requête et d’en-tête en arguments nommés, et enfin extra_headers: et timeout:. Les corps acceptent des clés symbole ou chaîne ; les réponses sont des Hash à clés chaîne avec les noms de champ de l’API elle-même (sent["id"]) : la référence de l’API les décrit donc champ par champ. emails, inboxes et broadcasts ont une méthode send, qui masque Object#send sur eux : appelez leurs méthodes de façon dynamique avec public_send.
Idempotence et nouvelles tentatives
Les huit opérations d’envoi (emails.send, emails.batch, réponses et transferts d’e-mails reçus, inboxes.send, inboxes.drafts.send, réponses et transferts dans un fil) envoient toujours un Idempotency-Key. Sans idempotency_key:, chaque appel en génère une que ses nouvelles tentatives réutilisent : une nouvelle tentative après un délai dépassé n’envoie donc jamais deux fois. Votre propre clé rend aussi sûre une répétition venue d’un autre processus.
Les échecs qui méritent une nouvelle tentative sont retentés deux fois par défaut : 429, 5xx, délais dépassés, erreurs réseau, et le 409 concurrent_idempotent_requests renvoyé tant que la première tentative avec la même clé est encore en cours. Seules les requêtes sans danger à répéter sont retentées : GET, PUT, DELETE et toute requête qui porte un Idempotency-Key, comme le fait chaque opération d’envoi. Le client attend ce que demande Retry-After et lève l’erreur aussitôt lorsqu’il demande plus d’une minute ; sinon il espace les tentatives de façon exponentielle, de 0,5 s à 8 s, diminuées au hasard d’un quart au plus. Chaque méthode accepte timeout: et extra_headers: pour cet appel, et celles d’envoi idempotency_key: ; max_retries: se règle sur le client.
Erreurs
Un appel qui échoue lève ValidationError (400, 422), AuthenticationError (401, ou aucune clé configurée), PermissionDeniedError (403), NotFoundError (404), ConflictError (409), RateLimitError (429, avec retry_after en secondes), APIError (5xx), APIConnectionError (aucune réponse) ou APITimeoutError (la tentative a dépassé son délai, un cas particulier de APIConnectionError). Toutes se trouvent dans le module BillionSend et étendent BillionSend::Error, levée telle quelle pour tout autre statut, avec status_code, name (le nom de l’erreur dans l’API), message et request_id, le x-request-id de la réponse, qui est l’identifiant de la requête dans la page Journaux du tableau de bord.
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
Listes
Les méthodes de liste renvoient une page. Chaque liste à curseur dispose aussi d’une méthode ..._all (search_all pour la recherche de fils) qui renvoie un Enumerator paresseux et va chercher les pages suivantes au fur et à mesure, en remontant lorsque before: est défini :
client.contacts.list_all(limit: 100).each do |contact|
puts contact["email"]
end
La boîte de réception d’un agent
Attendez les nouveaux e-mails sur le flux d’événements et répondez dans leur fil :
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) # events may be missing: read the threads again
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
Le flux se reconnecte avec Last-Event-ID lorsque la connexion tombe et rejoue ce qu’il a manqué. Gardez stream.last_event_id et repassez-le dans last_event_id: pour reprendre après un redémarrage. Un StreamGapEvent arrive une seule fois lorsque le flux reprend depuis plus de 24 heures en arrière. max_reconnects: (5 reconnexions ratées d’affilée par défaut ; 0 abandonne dès la première) règle la reconnexion, qui attend une seconde, ou ce que demande le champ retry du serveur, avant chaque tentative. Le flux d’une boîte de réception se termine une fois cette boîte supprimée ou expirée ; client.inboxes.events.stream suit toutes les boîtes que la clé peut lire.
Vérifier les webhooks
BillionSend.verify_webhook contrôle la signature et l’horodatage d’une livraison de webhook avec le secret whsec_ du endpoint, puis renvoie l’événement analysé. Passez le corps exactement tel qu’il est arrivé ; les noms d’en-tête sont reconnus quelle que soit la casse :
# 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
Une livraison de plus de cinq minutes est refusée, et pendant la rotation d’un secret, l’un ou l’autre secret est accepté.
Inscription d’un agent
signup = BillionSend::Client.new.agent.signup({ human_email: "owner@acme.dev", name: "Support agent" })
puts signup["inbox"]["email_address"]
L’appel n’a pas besoin de clé API ; la réponse contient la nouvelle clé et la boîte de réception. Voir Inscription d’un agent pour ce qu’un compte non réclamé peut faire.