---
title: SDK de Python
description: "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."
ai:
  exclude: true
---

El paquete `billionsend` es el cliente de BillionSend para Python. Cubre todas las operaciones de la [referencia de la API](/docs/es/api-reference): 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](https://github.com/billionsend/billionsend-python), en GitHub.

## Instalar

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

```sh
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

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

```python
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](/docs/es/agent-safety) 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](/docs/es/inboxes) 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

```python
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](/docs/es/concepts/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:

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

Con `AsyncBillionSend`, usa `async for`.

## Registro de agentes

```python
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](/docs/es/agent-signup) para saber qué puede hacer una cuenta sin reclamar.
