Saltar al contenido
Esc
↑↓navegar↵abrir⌘Jvista previa
En esta página

SDK de Ruby

Envía emails, trabaja con una bandeja de entrada y verifica webhooks desde Ruby con la gema billionsend: toda la API, reintentos y claves de idempotencia.

La gema billionsend es el cliente de BillionSend para Ruby. Cubre todas las operaciones de la referencia de la API: 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-ruby, en GitHub.

Instalar

Requiere Ruby 3.1 o superior. La gema no tiene dependencias de ejecución: usa net/http, json y openssl de la biblioteca estándar.

gem install billionsend

En un Gemfile, gem "billionsend".

Enviar un email

require "billionsend"

client = BillionSend::Client.new # lee BILLIONSEND_API_KEY

sent = client.emails.send({
  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")

puts sent["id"]

BillionSend::Client.new(api_key: "bs_...") recibe la clave directamente; base_url:, timeout: (segundos por intento, 60 por defecto), max_retries:, default_headers: y transport: (cualquier objeto que responda a call y open_stream como BillionSend::NetHTTPTransport, para enviar a través de tu propia pila HTTP) definen el resto. BILLIONSEND_BASE_URL sustituye la URL de la API.

Nombres de los métodos

Cada operación es un método con el nombre de su id en la referencia de la API: la ruta con puntos se convierte en una cadena de recursos en snake_case. emails.send es client.emails.send, emails.receiving.attachments.list es client.emails.receiving.attachments.list y agent.claimEmail es client.agent.claim_email. emails.metrics es client.emails.metrics.call, junto a .links, .countries y .clients.

Un método recibe los parámetros de ruta en orden, el cuerpo de la petición como un Hash entre llaves, luego los parámetros de consulta y de cabecera como argumentos con nombre y, al final, extra_headers: y timeout:. Los cuerpos admiten claves como símbolo o como cadena; las respuestas son Hashes 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. emails, inboxes y broadcasts tienen un método send, que oculta Object#send en ellos: para llamar a sus métodos de forma dinámica, usa public_send.

Idempotencia y reintentos

Las ocho operaciones de envío (emails.send, emails.batch, respuestas y reenvíos de correo recibido, inboxes.send, inboxes.drafts.send, respuestas y reenvíos de hilos) siempre mandan un Idempotency-Key. Sin idempotency_key:, cada llamada se inventa una que sus reintentos reutilizan, así que reintentar tras un timeout nunca envía dos veces. Una clave tuya también hace segura la repetición desde otro proceso.

Los fallos que merecen otro intento se reintentan dos veces por defecto: 429, 5xx, timeouts, errores de red 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 un Idempotency-Key, como hacen todas las operaciones de envío. El cliente espera lo que pida Retry-After y lanza 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, restando al azar hasta una cuarta parte. Todos los métodos aceptan timeout: y extra_headers: para esa llamada, y los de envío también idempotency_key:; max_retries: se define en el cliente.

Errores

Una llamada fallida lanza ValidationError (400, 422), AuthenticationError (401, o no hay clave configurada), 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, un tipo de APIConnectionError). Todos están en el módulo BillionSend y extienden BillionSend::Error, que se lanza tal cual para cualquier otro estado, con status_code, 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.

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

Los métodos de lista devuelven una página. Cada lista con cursor tiene además un método ..._all (search_all para la búsqueda de hilos) que devuelve un Enumerator diferido y va pidiendo las páginas siguientes, hacia atrás si se define before::

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

La bandeja de entrada de un agente

Espera email nuevo en el flujo de eventos y responde en su hilo:

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) # puede faltar algún evento: vuelve a leer los hilos

    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

El flujo se reconecta con Last-Event-ID cuando se corta la conexión y reenvía lo que se perdió. Guarda stream.last_event_id 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; 0 se rinde en la primera) ajusta la reconexión, que espera un segundo, o lo que pida el campo retry del servidor, antes de cada intento. El flujo de una bandeja termina cuando esa bandeja se elimina o caduca; client.inboxes.events.stream sigue todas las bandejas que la clave puede leer.

Verificar webhooks

BillionSend.verify_webhook comprueba la firma y la marca de tiempo de una entrega de webhook con el secreto whsec_ del endpoint y devuelve el evento ya interpretado. Pasa el cuerpo exactamente como llegó; los nombres de cabecera coinciden en mayúsculas o 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

Una entrega de más de cinco minutos se rechaza y, durante la rotación de un secreto, sirve cualquiera de los dos.

Registro de agentes

signup = BillionSend::Client.new.agent.signup({ human_email: "owner@acme.dev", name: "Support agent" })
puts signup["inbox"]["email_address"]

La llamada no necesita clave de API; la respuesta trae la clave nueva y la bandeja de entrada. Consulta Registro de agentes para saber qué puede hacer una cuenta sin reclamar.

¿Te ha resultado útil esta página?