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(comoinbox.email.received) ydata, un dict contype,created_at,inbox_idydata(la carga del evento de webhook del mismo nombre).StreamGapEvent:eventesstream.gapeidesNone. 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 ejemploclient.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.