SDK Elixir
Envoyez des e-mails, gérez une boîte de réception, vérifiez des webhooks en Elixir avec le package billionsend : toute l'API, nouvelles tentatives, idempotence.
Le package billionsend est le client BillionSend pour Elixir. Il 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-elixir.
Installer
Nécessite Elixir 1.18 ou plus récent et OTP 25 ou plus récent. Le package n’a aucune dépendance : il utilise :httpc et :ssl d’OTP, ainsi que le module JSON intégré à Elixir.
def deps do
[{:billionsend, "~> 0.1"}]
end
Envoyer un e-mail
client = BillionSend.client() # reads 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_...") prend la clé directement ; base_url:, timeout: (millisecondes par tentative, 60_000 par défaut), max_retries:, default_headers: et transport: (un {module, state} qui implémente BillionSend.Transport, pour envoyer par votre propre couche HTTP) règlent le reste. BILLIONSEND_BASE_URL remplace l’URL de l’API. Un client est une simple struct : construisez-le une seule fois et passez-le à chaque appel, depuis n’importe quel processus.
Noms des fonctions
Chaque opération est une fonction qui porte le nom de son identifiant dans la référence de l’API : les groupes du chemin séparé par des points forment le module et le dernier segment la fonction, le camelCase étant écrit en snake_case. emails.send devient BillionSend.Emails.send/3, emails.receiving.attachments.list devient BillionSend.Emails.Receiving.Attachments.list/3, et agent.claimEmail devient BillionSend.Agent.claim_email/2. emails.metrics devient BillionSend.Emails.metrics/2, à côté de BillionSend.Emails.Metrics.links/2, .countries/2 et .clients/2.
Une fonction prend le client, les paramètres de chemin dans l’ordre, le corps de la requête sous forme de map, puis une liste de mots-clés d’options : les paramètres de requête et d’en-tête (BillionSend.Emails.list(client, limit: 50) ; un paramètre de type liste accepte une liste), :extra_headers et :timeout, et, pour les fonctions d’envoi, :idempotency_key. Un corps que l’opération n’exige pas peut être omis. Une option inconnue, ou une option obligatoire manquante, lève une ArgumentError avant tout envoi. Chaque fonction renvoie {:ok, answer} ou {:error, error}, et sa jumelle en ! (BillionSend.Emails.send!/3) renvoie la réponse ou lève une exception. Les réponses sont le JSON de l’API décodé en maps à 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. BillionSend.Client.request(client, "GET", "/path", query: [...]) atteint tout ce que les fonctions ne couvrent pas.
Idempotence et nouvelles tentatives
Les huit fonctions d’envoi (Emails.send, Emails.batch, Emails.Receiving.reply et .forward, Inboxes.send, Inboxes.Drafts.send, Inboxes.Threads.Emails.reply et .forward) envoient toujours un Idempotency-Key. Sans idempotency_key:, chaque appel en génère une (un UUID) que ses nouvelles tentatives réutilisent : une nouvelle tentative après une connexion coupée n’envoie donc jamais deux fois ; votre propre clé rend aussi sûre une répétition venue d’un autre processus. La même clé avec une requête différente est refusée par une BillionSend.ConflictError.
Les échecs qui méritent une nouvelle tentative sont retentés deux fois par défaut : 429, 5xx, aucune réponse (échec de connexion, délai dépassé), 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 une clé d’idempotence, comme chaque envoi. Le client attend ce que demande Retry-After et renvoie l’erreur immédiatement lorsqu’il demande plus d’une minute ; sinon il espace les tentatives de façon exponentielle, de 0,5 s à 8 s, avec de la gigue. max_retries: se règle sur le client (0 désactive les nouvelles tentatives), et le processus appelant dort entre les tentatives.
Erreurs
Un appel qui échoue renvoie {:error, error} avec une struct d’exception : BillionSend.ValidationError (400, 422), AuthenticationError (401, ou aucune clé configurée, avec name valant missing_api_key avant tout envoi), 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). BillionSend.Error correspond à tout autre statut. Chacune porte status_code (nil en l’absence de réponse), 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. BillionSend.Errors.error?/1 distingue chacune d’elles des autres termes.
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
Listes
Les fonctions de liste renvoient une page. Chaque liste à curseur a aussi une fonction _all (search_all pour la recherche de fils) qui renvoie un Stream paresseux, allant chercher les pages suivantes au fur et à mesure, en remontant lorsque :before est défini :
client
|> BillionSend.Contacts.list_all(limit: 100)
|> Enum.each(&IO.puts(&1["email"]))
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 :
alias BillionSend.{Inboxes, InboxStreamEvent}
{:ok, events} = Inboxes.Events.stream_inbox(client, "support@acme.dev", types: "inbox.email.received")
events
|> Stream.filter(&match?(%InboxStreamEvent{}, &1)) # a StreamGapEvent: events may be missing, read the threads again
|> 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 ouvre le flux d’abord, de sorte qu’un flux refusé (une clé révoquée, une clé limitée à une boîte qui demande le flux de l’équipe) donne aussitôt un {:error, error} ; ce qu’elle renvoie est un Enumerable paresseux de structs BillionSend.InboxStreamEvent (id, event comme "inbox.email.received", et data, les champs "type", "created_at", "inbox_id" et "data" de la charge utile du webhook) et de structs BillionSend.StreamGapEvent. Le flux se reconnecte avec Last-Event-ID lorsque la connexion tombe et rejoue ce qu’il a manqué ; gardez l’id du dernier événement traité et repassez-le comme 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) règle la reconnexion, qui attend une seconde, ou ce que demande le champ retry du serveur, avant chaque tentative ; au-delà, l’énumération lève l’erreur de l’API pour la dernière tentative, ou BillionSend.APIConnectionError lorsqu’elle n’a reçu aucune réponse. Le flux d’une boîte de réception se termine une fois cette boîte supprimée ou expirée ; BillionSend.Inboxes.Events.stream/2 suit toutes les boîtes que la clé peut lire. Énumérez un flux une seule fois, dans le processus qui l’a ouvert : interrompre l’énumération (Enum.take/2, Stream.take_while/2) ferme la connexion.
Vérifier les webhooks
BillionSend.verify_webhook/4 contrôle la signature et l’horodatage d’une livraison de webhook avec le secret whsec_ du endpoint et renvoie {:ok, event} avec l’événement analysé, ou {:error, %BillionSend.WebhookVerificationError{}}. Passez le corps exactement tel qu’il est arrivé, avant tout parsing JSON ; les en-têtes peuvent être une map ou une liste de paires comme conn.req_headers, avec des noms dans n’importe quelle casse :
# 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
Une livraison de plus de cinq minutes est refusée (tolerance:, en secondes, permet de le changer), et pendant la rotation d’un secret, l’un ou l’autre secret est accepté. verify_webhook!/4 renvoie l’événement ou lève une exception ; un secret qui n’est pas un secret whsec_ lève une ArgumentError.