---
title: SDK para Ruby
description: Use o BillionSend em Ruby com a gem billionsend.
ai:
  exclude: true
---

A gem `billionsend` é o cliente do BillionSend para Ruby. Ela 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-ruby](https://github.com/billionsend/billionsend-ruby) no GitHub.

## Instalar

Requer Ruby 3.1 ou mais recente. A gem não tem dependências em tempo de execução: usa `net/http`, `json` e `openssl` da biblioteca padrão.

```sh
gem install billionsend -v 0.1.0
```

Num Gemfile, `gem "billionsend", "~> 0.1"`.

## Enviar um e-mail

```ruby
require "billionsend"

client = BillionSend::Client.new # reads BILLIONSEND_API_KEY

sent = client.emails.send({
  from: "Acme <hello@acme.dev>",
  to: ["ana@example.com"],
  subject: "Welcome to Acme",
  html: "<p>Glad you are here.</p>"
}, idempotency_key: "welcome/ana")

puts sent["id"]
```

`BillionSend::Client.new(api_key: "bs_...")` recebe a chave diretamente; `base_url:`, `timeout:` (segundos por tentativa, padrão de 60), `max_retries:`, `default_headers:` e `transport:` (qualquer objeto que responda a `call` e `open_stream` como `BillionSend::NetHTTPTransport`, para enviar pela sua própria pilha HTTP) definem o resto. `BILLIONSEND_BASE_URL` substitui a URL da API.

## Nomes dos métodos

Cada operação é um método com o nome do seu id na [referência da API](/docs/pt-br/api-reference), o caminho com pontos virando uma cadeia de recursos em snake_case: `emails.send` é `client.emails.send`, `emails.receiving.attachments.list` é `client.emails.receiving.attachments.list`, e `agent.claimEmail` é `client.agent.claim_email`. `emails.metrics` é `client.emails.metrics.call`, ao lado de `.links`, `.countries` e `.clients`.

Um método recebe os parâmetros de caminho em ordem, o corpo da requisição como um Hash entre chaves, depois os parâmetros de consulta e de cabeçalho como argumentos nomeados e por fim `extra_headers:` e `timeout:`. Os corpos aceitam chaves símbolo ou string; as respostas são Hashes 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. `emails`, `inboxes` e `broadcasts` têm um método `send`, que esconde `Object#send` neles: chame os métodos deles dinamicamente com `public_send`.

## Idempotência e novas tentativas

As oito operações de envio (`emails.send`, `emails.batch`, respostas e encaminhamentos de e-mails recebidos, `inboxes.send`, `inboxes.drafts.send`, respostas e encaminhamentos em conversas) sempre enviam um `Idempotency-Key`. Sem `idempotency_key:`, cada chamada cria uma chave que as suas novas tentativas reutilizam, então uma nova tentativa depois de um timeout nunca envia duas vezes; a sua própria chave também deixa segura uma repetição vinda de outro processo.

Falhas que valem nova tentativa são repetidas duas vezes por padrão: 429, 5xx, timeouts, erros de rede 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 um `Idempotency-Key`, como toda operação de envio. O cliente espera o que o `Retry-After` pede, e lança o erro na hora quando ele pede mais de um minuto; senão recua exponencialmente de 0,5 s até 8 s, menos até um quarto ao acaso. Todo método aceita `timeout:` e `extra_headers:` para aquela chamada, e os de envio `idempotency_key:`; `max_retries:` é definido no cliente.

## Erros

Uma chamada que falha lança `ValidationError` (400, 422), `AuthenticationError` (401, ou nenhuma chave configurada), `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, um tipo de `APIConnectionError`). Todas ficam no módulo `BillionSend` e estendem `BillionSend::Error`, lançado ele mesmo para qualquer outro status, com `status_code`, `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.

```ruby
begin
  puts client.emails.get(id)["subject"]
rescue BillionSend::NotFoundError
  # no such email
rescue BillionSend::Error => e
  warn "#{e.status_code} #{e.name}: #{e.message} (request #{e.request_id})"
end
```

## Listas

Os métodos de lista devolvem uma página. Toda lista com cursor também tem um método `..._all` (`search_all` na busca de conversas) que devolve um `Enumerator` preguiçoso, buscando as páginas seguintes conforme avança, para trás quando `before:` está definido:

```ruby
client.contacts.list_all(limit: 100).each do |contact|
  puts contact["email"]
end
```

## A caixa de entrada de um agente

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

```ruby
stream = client.inboxes.events.stream_inbox("support@acme.dev", types: "inbox.email.received")
begin
  stream.each do |event|
    next if event.is_a?(BillionSend::StreamGapEvent) # events may be missing: read the threads again

    data = event.data["data"]
    client.inboxes.threads.emails.reply(
      event.data["inbox_id"], data["thread_id"], data["email_id"],
      { text: "Thanks, we are on it." },
      idempotency_key: "reply/#{data["email_id"]}"
    )
  end
ensure
  stream.close
end
```

O fluxo se reconecta com `Last-Event-ID` quando a conexão cai e reenvia o que perdeu; guarde `stream.last_event_id` e passe-o de volta em `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; `0` desiste na primeira) ajusta a reconexão, que espera um segundo, ou o que o campo `retry` do servidor pedir, antes de cada tentativa. O fluxo de uma caixa termina depois que essa caixa é excluída ou expira; `client.inboxes.events.stream` acompanha todas as caixas que a chave pode ler.

## Verificar webhooks

`BillionSend.verify_webhook` 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 o evento já interpretado. Passe o corpo exatamente como chegou; os nomes dos cabeçalhos valem em maiúsculas ou minúsculas:

```ruby
# config.ru
require "billionsend"

SECRET = ENV.fetch("BILLIONSEND_WEBHOOK_SECRET")
NAMES = %w[webhook-id webhook-timestamp webhook-signature].freeze

app = lambda do |env|
  headers = NAMES.to_h { |name| [name, env["HTTP_#{name.upcase.tr("-", "_")}"]] }
  event = BillionSend.verify_webhook(env["rack.input"].read, headers, SECRET)
  warn event["type"]
  [204, {}, []]
rescue BillionSend::WebhookVerificationError
  [400, {}, ["bad signature"]]
end

run app
```

Uma entrega com mais de cinco minutos é recusada, e durante a rotação de um segredo qualquer um dos dois verifica.
