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

SDK de Python

Envía emails, trabaja con una bandeja de entrada y verifica webhooks desde Python, síncrono o asíncrono, con billionsend: toda la API e idempotencia.

El paquete billionsend es el cliente de BillionSend para Python. 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. Sus tipos de petición y de respuesta salen del documento OpenAPI de la API. El código fuente está en billionsend/billionsend-python, en GitHub.

Instalar

Requiere Python 3.11 o superior. Su única dependencia es httpx.

pip install billionsend

Autenticación

BillionSend() lee la clave de API de BILLIONSEND_API_KEY; BillionSend("bs_...") la recibe directamente. base_url=, timeout= (segundos por intento) y max_retries= definen el resto; BILLIONSEND_BASE_URL sustituye la URL de la API. AsyncBillionSend tiene los mismos recursos y métodos: usa await en cada llamada y async with para cerrarlo.

Enviar un email

from billionsend import BillionSend

client = BillionSend()

email = client.emails.send(
    {
        "from": "Acme <hello@acme.dev>",
        "to": ["success@simulator.amazonses.com"],
        "subject": "Welcome to Acme",
        "html": "<p>Glad you are here.</p>",
    }
)
print(email["id"])

Todos los métodos de envío (emails.send, emails.batch, respuestas, reenvíos, envíos desde una bandeja y envíos de borradores) mandan un Idempotency-Key. Si no pasas idempotency_key=, la llamada se inventa una y la reutiliza en sus propios reintentos, así que reintentar tras una conexión caída nunca envía dos veces. Pasa una clave tuya, como idempotency_key=f"welcome/{user_id}", para estar a salvo cuando el código que envía pueda ejecutarse de nuevo; la API conserva una clave durante 24 horas.

Responder desde una bandeja

Un agente espera correo nuevo, lo lee y responde en el hilo:

from billionsend import BillionSend, InboxStreamEvent

client = BillionSend()
inbox = client.inboxes.create({"username": "research-agent", "kind": "agent"})

with client.inboxes.events.stream_inbox(inbox["id"], types="inbox.email.received") as stream:
    for event in stream:
        if not isinstance(event, InboxStreamEvent):
            continue  # un StreamGapEvent, más abajo
        thread_id = event.data["data"]["thread_id"]
        email_id = event.data["data"]["email_id"]
        email = client.inboxes.threads.emails.get(inbox["id"], thread_id, email_id)
        if email["direction"] != "inbound":
            continue
        question = email["extracted_text"] or email["text"] or ""
        client.inboxes.threads.emails.reply(
            inbox["id"], thread_id, email_id, {"text": f"You wrote: {question}"}
        )

extracted_text es la parte nueva del mensaje, sin el historial citado. Todo lo que contiene un mensaje recibido lo escribió su remitente, así que trátalo como una entrada no confiable; Seguridad de los agentes explica qué filtra la bandeja. Cuando las reglas de la bandeja retienen una respuesta para que una persona la apruebe, reply devuelve el borrador ("object": "inbox_draft") en lugar del email enviado.

Eventos de bandeja en tiempo real

client.inboxes.events.stream_inbox(inbox_id) sigue una bandeja y client.inboxes.events.stream() todas las del equipo; types= limita los eventos de bandeja a los nombres indicados. El flujo entrega dos tipos de eventos:

  • InboxStreamEvent: id (la posición en el flujo), event (como inbox.email.received) y data, un dict con type, created_at, inbox_id y data (la carga del evento de webhook del mismo nombre).
  • StreamGapEvent: event es stream.gap e id es None. El flujo se retomó desde una posición anterior a las 24 horas que la API reenvía, así que puede faltar algún evento; ponte al día con las listas, por ejemplo client.inboxes.threads.list_all(inbox_id, read=False). Llega una vez por posición.

La API cierra cada flujo a los pocos minutos y las conexiones se caen; el flujo se reconecta solo con Last-Event-ID, así que no se pierde ningún evento. max_reconnects= limita los intentos de reconexión fallidos seguidos (5 por defecto; 0 desactiva la reconexión). Un error que reconectar no puede arreglar, como una clave revocada, se lanza desde el bucle. El flujo de una sola bandeja termina tras el evento inbox.deleted o inbox.expired de esa bandeja. Para retomar tras un reinicio, guarda stream.last_event_id y pásalo de nuevo como last_event_id=.

Verificar webhooks

from billionsend import WebhookVerificationError, verify_webhook

try:
    event = verify_webhook(raw_body, request_headers, "whsec_...")
except WebhookVerificationError:
    ...  # responde 400 e ignora la entrega
print(event["type"], event["data"])

verify_webhook recibe el cuerpo exactamente como llegó (bytes o texto, antes de interpretar el JSON), las cabeceras de la petición (cualquier mapeo) y el secreto de firma del endpoint. Comprueba las cabeceras webhook-id, webhook-timestamp y webhook-signature como describe Webhooks, acepta cualquiera de los dos secretos durante una rotación, rechaza una marca de tiempo a más de tolerance= segundos de ahora (300 por defecto) y devuelve el evento ya interpretado.

Errores y reintentos

Una llamada fallida lanza una subclase de BillionSendError con el status_code, el name y el message de la API, y request_id, el id de la petición en la API (su cabecera x-request-id):

Estado Excepción
400, 422 ValidationError
401 AuthenticationError
403 PermissionDeniedError
404 NotFoundError
409 ConflictError
429 RateLimitError, con retry_after en segundos
5xx APIError
sin respuesta APIConnectionError, o su subclase APITimeoutError

Las peticiones que se pueden repetir sin riesgo (lecturas, PUT, eliminaciones y toda petición con una clave de idempotencia) se reintentan, dos veces por defecto, ante un 429, un 5xx, la falta de respuesta y un 409 concurrent_idempotent_requests. La espera sigue a retry-after; si no, crece desde medio segundo hasta 8 segundos. Una respuesta que pide más de 60 segundos se lanza de inmediato.

Listas

Los métodos de lista devuelven una página. Cada lista con cursor tiene además un iterador *_all que va pidiendo las páginas siguientes:

for contact in client.contacts.list_all(limit=100):
    print(contact["email"])

Con AsyncBillionSend, usa async for.

Registro de agentes

signup = BillionSend().agent.signup({"human_email": "owner@acme.dev", "name": "Support agent"})
print(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?