SDK para Python
Use o BillionSend em Python, síncrono ou assíncrono, com o pacote billionsend.
O pacote billionsend é o cliente do BillionSend para Python. Ele cobre todas as operações da referência da API: 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 no GitHub.
Instalar
Precisa do Python 3.11 ou mais novo. A única dependência é httpx.
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
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:
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 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 aos nomes dados. O stream entrega dois tipos de evento:
InboxStreamEvent:id(a posição no stream),event(comoinbox.email.received) edata, um dict comtype,created_at,inbox_idedata(o payload do evento de webhook de mesmo nome).StreamGapEvent:eventéstream.gapeidé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 exemploclient.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
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, 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:
for contact in client.contacts.list_all(limit=100):
print(contact["email"])
Com AsyncBillionSend, use async for.
Cadastro de agentes
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 para o que uma conta ainda não reivindicada pode fazer.