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

SDK para Ruby

Use o BillionSend em Ruby com a gem billionsend.

A gem billionsend é o cliente do BillionSend para Ruby. Ela 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-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.

gem install billionsend -v 0.1.0

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

Enviar um e-mail

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

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:

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

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

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

Esta página foi útil?