---
title: SDK para Elixir
description: Use o BillionSend em Elixir com o pacote billionsend do Hex.
ai:
  exclude: true
---

O pacote `billionsend` é o cliente do BillionSend para Elixir. Ele cobre todas as operações da [referência da API](/docs/pt-br/api-reference): envio, domínios, contatos, broadcasts, templates, webhooks, caixas de entrada com suas conversas e rascunhos, eventos das caixas de entrada em tempo real e cadastro de agentes. O código-fonte está em [billionsend/billionsend-elixir](https://github.com/billionsend/billionsend-elixir) no GitHub.

## Instalar

Requer Elixir 1.18 ou mais recente e OTP 25 ou mais recente. O pacote não tem dependências: usa `:httpc` e `:ssl` do OTP e o `JSON` embutido do Elixir.

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

## Enviar um e-mail

```elixir
client = BillionSend.client()  # reads BILLIONSEND_API_KEY

{:ok, sent} =
  BillionSend.Emails.send(
    client,
    %{
      from: "Acme <hello@acme.dev>",
      to: ["ana@example.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_...")` recebe a chave diretamente; `base_url:`, `timeout:` (milissegundos por tentativa, padrão de `60_000`), `max_retries:`, `default_headers:` e `transport:` (um `{module, state}` que implementa `BillionSend.Transport`, para enviar pela sua própria camada HTTP) definem o resto. `BILLIONSEND_BASE_URL` substitui a URL da API. Um cliente é uma struct simples: crie-o uma vez e passe-o a toda chamada, de qualquer processo.

## Nomes dos métodos

Cada operação é uma função com o nome do seu id na [referência da API](/docs/pt-br/api-reference): os grupos do caminho com pontos formam o módulo e o último segmento é a função, com camelCase escrito em snake_case. `emails.send` é `BillionSend.Emails.send/3`, `emails.receiving.attachments.list` é `BillionSend.Emails.Receiving.Attachments.list/3`, e `agent.claimEmail` é `BillionSend.Agent.claim_email/2`. `emails.metrics` é `BillionSend.Emails.metrics/2`, ao lado de `BillionSend.Emails.Metrics.links/2`, `.countries/2` e `.clients/2`.

Uma função recebe o cliente, os parâmetros de caminho em ordem, o corpo da requisição como um mapa, depois uma lista de opções (keyword list): os parâmetros de consulta e de cabeçalho (`BillionSend.Emails.list(client, limit: 50)`; um parâmetro de lista recebe uma lista), `:extra_headers` e `:timeout`, e nas funções de envio `:idempotency_key`. Um corpo que a operação não exige pode ser omitido. Uma opção desconhecida, ou uma obrigatória que falta, lança `ArgumentError` antes de qualquer envio. Toda função devolve `{:ok, answer}` ou `{:error, error}`, e a sua gêmea com `!` (`BillionSend.Emails.send!/3`) devolve a resposta ou lança o erro. As respostas são o JSON da API decodificado em mapas com chaves string e os nomes de campo da própria API (`sent["id"]`), então a referência da API os descreve campo a campo. `BillionSend.Client.request(client, "GET", "/path", query: [...])` alcança o que as funções não cobrem.

## Idempotência e novas tentativas

As oito funções de envio (`Emails.send`, `Emails.batch`, `Emails.Receiving.reply` e `.forward`, `Inboxes.send`, `Inboxes.Drafts.send`, `Inboxes.Threads.Emails.reply` e `.forward`) sempre enviam um `Idempotency-Key`. Sem `idempotency_key:`, cada chamada cria uma chave (um UUID) que as suas novas tentativas reutilizam, então uma nova tentativa depois de uma conexão interrompida nunca envia duas vezes; a sua própria chave também deixa segura uma repetição vinda de outro processo. A mesma chave com uma requisição diferente é recusada com um `BillionSend.ConflictError`.

Falhas que valem nova tentativa são repetidas duas vezes por padrão: 429, 5xx, nenhuma resposta (falha de conexão, timeout) e o `409 concurrent_idempotent_requests` respondido enquanto a primeira tentativa com a mesma chave ainda está em andamento. Só são repetidas as requisições seguras de repetir: GET, PUT, DELETE e qualquer requisição que leve uma chave de idempotência, como todo envio. O cliente espera o que o `Retry-After` pede e devolve o erro na hora quando ele pede mais de um minuto; senão recua exponencialmente de 0,5 s até 8 s, com variação aleatória. `max_retries:` é definido no cliente (`0` desliga as novas tentativas), e o processo que chama dorme entre as tentativas.

## Erros

Uma chamada que falha devolve `{:error, error}` com uma struct de exceção: `BillionSend.ValidationError` (400, 422), `AuthenticationError` (401, ou nenhuma chave configurada, com `name` igual a `missing_api_key` antes de qualquer envio), `PermissionDeniedError` (403), `NotFoundError` (404), `ConflictError` (409), `RateLimitError` (429, com `retry_after` em segundos), `APIError` (5xx), `APIConnectionError` (sem resposta) ou `APITimeoutError` (a tentativa estourou o tempo). `BillionSend.Error` é qualquer outro status. Cada uma traz `status_code` (`nil` quando não houve resposta), `name` (o nome do erro na API), `message` e `request_id`, o `x-request-id` da resposta, que é o id da requisição na página Logs do painel. `BillionSend.Errors.error?/1` distingue qualquer uma delas de outros termos.

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

As funções de lista devolvem uma página. Toda lista com cursor também tem uma função `_all` (`search_all` na busca de conversas) que devolve uma `Stream` preguiçosa, buscando as páginas seguintes conforme avança, para trás quando `:before` está definido:

```elixir
client
|> BillionSend.Contacts.list_all(limit: 100)
|> Enum.each(&IO.puts(&1["email"]))
```

## A caixa de entrada de um agente

Espere e-mails novos no [fluxo de eventos](/docs/pt-br/inboxes) e responda na conversa:

```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))  # 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` abre o fluxo primeiro, então um fluxo recusado (uma chave revogada, uma chave presa a uma caixa pedindo o fluxo do time) vira um `{:error, error}` na hora; o que ela devolve é um `Enumerable` preguiçoso de structs `BillionSend.InboxStreamEvent` (`id`, `event` como `"inbox.email.received"`, e `data`, com `"type"`, `"created_at"`, `"inbox_id"` e `"data"` do payload do webhook) e `BillionSend.StreamGapEvent`. O fluxo se reconecta com `Last-Event-ID` quando a conexão cai e reenvia o que perdeu; guarde o `id` do último evento tratado e passe-o de volta como `last_event_id:` para retomar depois de reiniciar. Um `StreamGapEvent` chega uma vez quando o fluxo é retomado de mais de 24 horas atrás. `max_reconnects:` (padrão de 5 reconexões que falham em sequência) ajusta a reconexão, que espera um segundo, ou o que o campo `retry` do servidor pedir, antes de cada tentativa; passado esse limite a enumeração lança o erro da API da última tentativa, ou `BillionSend.APIConnectionError` quando não houve resposta. O fluxo de uma caixa termina depois que essa caixa é excluída ou expira; `BillionSend.Inboxes.Events.stream/2` acompanha todas as caixas que a chave pode ler. Enumere um fluxo uma só vez, no processo que o abriu: interromper a enumeração (`Enum.take/2`, `Stream.take_while/2`) fecha a conexão.

## Verificar webhooks

`BillionSend.verify_webhook/4` confere a assinatura e o horário de uma entrega de [webhook](/docs/pt-br/concepts/webhooks) com o segredo `whsec_` do endpoint e devolve `{:ok, event}` com o evento já interpretado, ou `{:error, %BillionSend.WebhookVerificationError{}}`. Passe o corpo exatamente como chegou, antes de qualquer interpretação do JSON; os cabeçalhos podem ser um mapa ou uma lista de pares como `conn.req_headers`, com nomes em maiúsculas ou minúsculas:

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

Uma entrega com mais de cinco minutos é recusada (`tolerance:`, em segundos, muda isso), e durante a rotação de um segredo qualquer um dos dois verifica. `verify_webhook!/4` devolve o evento ou lança o erro; um segredo que não seja `whsec_` lança `ArgumentError`.
