---
title: SDK de Elixir
description: "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."
ai:
  exclude: true
---

El paquete `billionsend` es el cliente de BillionSend para Elixir. Cubre todas las operaciones de la [referencia de la API](/docs/es/api-reference): 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](https://github.com/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.

```elixir
def deps do
  [{:billionsend, "~> 0.1"}]
end
```

## Enviar un email

```elixir
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](/docs/es/api-reference): 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.

```elixir
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`:

```elixir
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](/docs/es/inboxes) y responde en su hilo:

```elixir
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](/docs/es/concepts/webhooks) 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:

```elixir
# 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`.
