SDK de Elixir
Envía emails, trabaja con una bandeja de entrada y verifica webhooks desde Elixir con el paquete billionsend de Hex: toda la API, reintentos e idempotencia.
El paquete billionsend es el cliente de BillionSend para Elixir. Cubre todas las operaciones de la referencia de la API: envío, dominios, contactos, envíos masivos, plantillas, webhooks, bandejas de entrada con sus hilos y borradores, eventos de bandeja en tiempo real y registro de agentes. El código fuente está en billionsend/billionsend-elixir, en GitHub.
Instalar
Requiere Elixir 1.18 o superior y OTP 25 o superior. El paquete no tiene dependencias: usa :httpc y :ssl de OTP y el JSON incorporado de Elixir.
def deps do
[{:billionsend, "~> 0.1"}]
end
Enviar un email
client = BillionSend.client() # lee 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_...") recibe la clave directamente; base_url:, timeout: (milisegundos por intento, 60_000 por defecto), max_retries:, default_headers: y transport: (un {module, state} que implementa BillionSend.Transport, para enviar por tu propia capa HTTP) definen el resto. BILLIONSEND_BASE_URL sustituye la URL de la API. Un cliente es una struct simple: créalo una vez y pásalo a cada llamada, desde cualquier proceso.
Nombres de las funciones
Cada operación es una función con el nombre de su id en la referencia de la API: los grupos de la ruta separada por puntos forman el módulo y el último segmento es la función, con el camelCase escrito en snake_case. emails.send es BillionSend.Emails.send/3, emails.receiving.attachments.list es BillionSend.Emails.Receiving.Attachments.list/3 y agent.claimEmail es BillionSend.Agent.claim_email/2. emails.metrics es BillionSend.Emails.metrics/2, junto a BillionSend.Emails.Metrics.links/2, .countries/2 y .clients/2.
Una función recibe el cliente, los parámetros de ruta en orden, el cuerpo de la petición como mapa y, después, una lista de opciones con clave: los parámetros de consulta y de cabecera (BillionSend.Emails.list(client, limit: 50); un parámetro de lista recibe una lista), :extra_headers y :timeout, y en las funciones de envío :idempotency_key. Un cuerpo que la operación no exige puede omitirse. Una opción desconocida, o una obligatoria que falta, lanza ArgumentError antes de enviar nada. Cada función devuelve {:ok, answer} o {:error, error}, y su gemela con ! (BillionSend.Emails.send!/3) devuelve la respuesta o lanza una excepción. Las respuestas son el JSON de la API decodificado en mapas con claves de cadena y los nombres de campo propios de la API (sent["id"]), así que la referencia de la API las describe campo por campo. BillionSend.Client.request(client, "GET", "/path", query: [...]) llega a todo lo que las funciones no cubren.
Idempotencia y reintentos
Las ocho funciones de envío (Emails.send, Emails.batch, Emails.Receiving.reply y .forward, Inboxes.send, Inboxes.Drafts.send, Inboxes.Threads.Emails.reply y .forward) siempre mandan un Idempotency-Key. Si no pasas idempotency_key:, cada llamada se inventa una (un UUID) que sus reintentos reutilizan, así que reintentar tras una conexión caída nunca envía dos veces; una clave tuya también hace segura la repetición desde otro proceso. La misma clave con una petición distinta se rechaza con un BillionSend.ConflictError.
Los fallos que merecen otro intento se reintentan dos veces por defecto: 429, 5xx, la falta de respuesta (fallo de conexión, timeout) y el 409 concurrent_idempotent_requests que se devuelve mientras el primer intento con la misma clave sigue en curso. Solo se reintentan las peticiones que se pueden repetir sin riesgo: GET, PUT, DELETE y cualquier petición con una clave de idempotencia, como todo envío. El cliente espera lo que pida Retry-After y devuelve el error de inmediato si pide más de un minuto; si no, aumenta la espera de forma exponencial de 0,5 s a 8 s, con variación aleatoria. max_retries: se define en el cliente (0 desactiva los reintentos), y el proceso que llama duerme entre intentos.
Errores
Una llamada fallida devuelve {:error, error} con una struct de excepción: BillionSend.ValidationError (400, 422), AuthenticationError (401, o no hay clave configurada, con name igual a missing_api_key antes de enviar nada), PermissionDeniedError (403), NotFoundError (404), ConflictError (409), RateLimitError (429, con retry_after en segundos), APIError (5xx), APIConnectionError (sin respuesta) o APITimeoutError (el intento agotó el tiempo). BillionSend.Error es cualquier otro estado. Cada una trae status_code (nil si no hubo respuesta), name (el nombre del error de la API), message y request_id, el x-request-id de la respuesta, que es el id de la petición en la página Registros del panel. BillionSend.Errors.error?/1 distingue cualquiera de ellas de otros términos.
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
Listas
Las funciones de lista devuelven una página. Cada lista con cursor tiene además una función _all (search_all en la búsqueda de hilos) que devuelve un Stream perezoso y va pidiendo las páginas siguientes a medida que avanza, hacia atrás si se define :before:
client
|> BillionSend.Contacts.list_all(limit: 100)
|> Enum.each(&IO.puts(&1["email"]))
La bandeja de entrada de un agente
Espera email nuevo en el flujo de eventos y responde en su hilo:
alias BillionSend.{Inboxes, InboxStreamEvent}
{:ok, events} = Inboxes.Events.stream_inbox(client, "support@acme.dev", types: "inbox.email.received")
events
|> Stream.filter(&match?(%InboxStreamEvent{}, &1)) # un StreamGapEvent: puede faltar algún evento, vuelve a leer los hilos
|> 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 abre primero el flujo, así que un flujo rechazado (una clave revocada, o una clave limitada a una bandeja que pide el flujo del equipo) es un {:error, error} de inmediato; lo que devuelve es un Enumerable perezoso de structs BillionSend.InboxStreamEvent (id, event, como "inbox.email.received", y data, el "type", "created_at", "inbox_id" y "data" del payload del webhook) y structs BillionSend.StreamGapEvent. El flujo se reconecta con Last-Event-ID cuando se corta la conexión y reenvía lo que se perdió; guarda el id del último evento que procesaste y pásalo de nuevo como last_event_id: para retomarlo tras un reinicio. Un StreamGapEvent llega una sola vez, cuando el flujo se retoma desde hace más de 24 horas. max_reconnects: (5 reconexiones fallidas seguidas por defecto) ajusta la reconexión, que espera un segundo, o lo que pida el campo retry del servidor, antes de cada intento; pasado ese límite, la enumeración lanza el error de la API del último intento, o BillionSend.APIConnectionError si no obtuvo respuesta. El flujo de una bandeja termina cuando esa bandeja se elimina o caduca; BillionSend.Inboxes.Events.stream/2 sigue todas las bandejas que la clave puede leer. Enumera un flujo una sola vez, en el proceso que lo abrió: detener la enumeración (Enum.take/2, Stream.take_while/2) cierra la conexión.
Verificar webhooks
BillionSend.verify_webhook/4 comprueba la firma y la marca de tiempo de una entrega de webhook con el secreto whsec_ del endpoint y devuelve {:ok, event} con el evento ya interpretado, o {:error, %BillionSend.WebhookVerificationError{}}. Pasa el cuerpo exactamente como llegó, antes de cualquier interpretación del JSON; las cabeceras pueden ser un mapa o una lista de pares como conn.req_headers, con los nombres en cualquier combinación de mayúsculas y minúsculas:
# Phoenix: conserva el cuerpo sin procesar (un :body_reader de Plug.Parsers que lo guarda en 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
Una entrega de más de cinco minutos se rechaza (tolerance:, en segundos, lo cambia) y, durante la rotación de un secreto, sirve cualquiera de los dos. verify_webhook!/4 devuelve el evento o lanza una excepción; un secreto que no es un secreto whsec_ lanza ArgumentError.