Pular para o conteúdo
Esc
↑↓navegar↵abrir⌘Jpré-visualizar
Nesta página

SDK para Elixir

Use o BillionSend em Elixir com o pacote billionsend do Hex.

O pacote billionsend é o cliente do BillionSend para Elixir. Ele cobre todas as operações da referência da API: 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 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.

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

Enviar um e-mail

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: 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.

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:

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 e responda na conversa:

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

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

Esta página foi útil?