Aller au contenu
Esc
↑↓naviguer↵ouvrir⌘Japerçu
Sur cette page

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.

Cette page vous a-t-elle été utile ?