---
title: SDK para Python
description: Use o BillionSend em Python, síncrono ou assíncrono, com o pacote billionsend.
ai:
  exclude: true
---

O pacote `billionsend` é o cliente do BillionSend para Python. Ele cobre todas as operações da [referência da API](/docs/pt-br/api-reference): 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. Os tipos de requisição e resposta vêm do documento OpenAPI da API. O código-fonte está em [billionsend/billionsend-python](https://github.com/billionsend/billionsend-python) no GitHub.

## Instalar

Precisa do Python 3.11 ou mais novo. A única dependência é `httpx`.

```sh
pip install billionsend
```

## Autenticar

`BillionSend()` lê a chave de API de `BILLIONSEND_API_KEY`; `BillionSend("bs_...")` recebe a chave direto. `base_url=`, `timeout=` (segundos por tentativa) e `max_retries=` configuram o resto; `BILLIONSEND_BASE_URL` substitui a URL da API. `AsyncBillionSend` tem os mesmos recursos e métodos; use `await` em cada chamada e `async with` para fechá-lo.

## Enviar um e-mail

```python
from billionsend import BillionSend

client = BillionSend()

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

Todo método de envio (`emails.send`, `emails.batch`, respostas, encaminhamentos, envios da caixa de entrada e envios de rascunhos) manda um `Idempotency-Key`. Sem `idempotency_key=`, a chamada cria uma chave e a reutiliza nas próprias novas tentativas, então repetir depois de uma conexão perdida nunca envia duas vezes. Passe sua própria chave, como `idempotency_key=f"welcome/{user_id}"`, para continuar seguro quando o código que envia puder rodar de novo; a API guarda uma chave por 24 horas.

## Responder uma caixa de entrada

Um agente espera e-mails novos, lê cada um e responde na conversa:

```python
from billionsend import BillionSend, InboxStreamEvent

client = BillionSend()
inbox = client.inboxes.create({"username": "support", "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  # a StreamGapEvent, see below
        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` é a parte nova da mensagem, sem o histórico citado. Tudo numa mensagem recebida foi escrito por quem a enviou, então trate como entrada não confiável; [Segurança do agente](/docs/pt-br/agent-safety) explica o que a caixa de entrada filtra. Quando as regras da caixa de entrada seguram uma resposta para uma pessoa aprovar, `reply` devolve o rascunho (`"object": "inbox_draft"`) em vez do e-mail enviado.

## Eventos da caixa de entrada em tempo real

`client.inboxes.events.stream_inbox(inbox_id)` acompanha uma caixa de entrada e `client.inboxes.events.stream()` todas as caixas da equipe; `types=` limita os [eventos da caixa de entrada](/docs/pt-br/inboxes) aos nomes dados. O stream entrega dois tipos de evento:

- `InboxStreamEvent`: `id` (a posição no stream), `event` (como `inbox.email.received`) e `data`, um dict com `type`, `created_at`, `inbox_id` e `data` (o payload do evento de webhook de mesmo nome).
- `StreamGapEvent`: `event` é `stream.gap` e `id` é `None`. O stream foi retomado de uma posição mais antiga que as 24 horas que a API reenvia, então podem faltar eventos; recupere pelas listas, por exemplo `client.inboxes.threads.list_all(inbox_id, read=False)`. Ele chega uma vez por posição.

A API encerra cada stream depois de alguns minutos e conexões caem; o stream reconecta sozinho com `Last-Event-ID`, então nenhum evento se perde. `max_reconnects=` limita as reconexões que falham em sequência (5 por padrão, `0` desliga a reconexão). Um erro que reconectar não resolve, como uma chave revogada, é lançado no loop. O stream de uma caixa de entrada termina depois do evento `inbox.deleted` ou `inbox.expired` dela. Para retomar depois de reiniciar, guarde `stream.last_event_id` e passe de volta como `last_event_id=`.

## Verificar webhooks

```python
from billionsend import WebhookVerificationError, verify_webhook

try:
    event = verify_webhook(raw_body, request_headers, "whsec_...")
except WebhookVerificationError:
    ...  # answer 400 and ignore the delivery
print(event["type"], event["data"])
```

`verify_webhook` recebe o corpo exatamente como chegou (bytes ou texto, antes de qualquer parse de JSON), os cabeçalhos da requisição (qualquer mapping) e o segredo de assinatura do endpoint. Ele confere os cabeçalhos `webhook-id`, `webhook-timestamp` e `webhook-signature` como descrito em [Webhooks](/docs/pt-br/concepts/webhooks), aceita qualquer um dos dois segredos durante uma rotação, recusa um timestamp a mais de `tolerance=` segundos (300 por padrão) de agora e devolve o evento já lido.

## Erros e novas tentativas

Uma chamada que falha lança uma subclasse de `BillionSendError` com `status_code`, `name` e `message` da API, e `request_id`, o id da requisição na API (o cabeçalho `x-request-id`):

| Status | Exceção |
| --- | --- |
| 400, 422 | `ValidationError` |
| 401 | `AuthenticationError` |
| 403 | `PermissionDeniedError` |
| 404 | `NotFoundError` |
| 409 | `ConflictError` |
| 429 | `RateLimitError`, com `retry_after` em segundos |
| 5xx | `APIError` |
| sem resposta | `APIConnectionError`, ou a subclasse `APITimeoutError` |

Requisições que podem ser repetidas com segurança (leituras, `PUT`, exclusões e toda requisição com chave de idempotência) são tentadas de novo, duas vezes por padrão, em 429, em 5xx, quando nenhuma resposta voltou e em 409 `concurrent_idempotent_requests`. A espera segue `retry-after`; sem ele, cresce de meio segundo até 8 segundos. Uma resposta que pede mais de 60 segundos é lançada na hora.

## Listas

Os métodos de lista devolvem uma página. Toda lista com cursor também tem um iterador `*_all` que busca as próximas páginas conforme avança:

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

Com `AsyncBillionSend`, use `async for`.

## Cadastro de agentes

```python
signup = BillionSend().agent.signup({"human_email": "owner@acme.dev", "name": "Support agent"})
print(signup["inbox"]["email_address"])
```

A chamada não precisa de chave de API; a resposta traz a nova chave e a caixa de entrada. Veja [Cadastro de agentes](/docs/pt-br/agent-signup) para o que uma conta ainda não reivindicada pode fazer.
