Python-SDK
E-Mails senden, Postfach bedienen, Webhooks verifizieren mit dem Paket billionsend, sync oder async: jede API-Operation, Wiederholungen, Idempotenzschlüssel.
Das Paket billionsend ist der BillionSend-Client für Python. Es deckt jede Operation der API-Referenz ab: Versand, Domains, Kontakte, Newsletter-Versand, Vorlagen, Webhooks, Postfächer mit ihren Threads und Entwürfen, Live-Ereignisse von Postfächern und die Agent-Registrierung. Seine Anfrage- und Antworttypen stammen aus dem OpenAPI-Dokument der API. Der Quellcode liegt auf GitHub unter billionsend/billionsend-python.
Installation
Erfordert Python 3.11 oder neuer. Die einzige Abhängigkeit ist httpx.
pip install billionsend
Authentifizierung
BillionSend() liest den API-Schlüssel aus BILLIONSEND_API_KEY, BillionSend("bs_...") nimmt ihn direkt entgegen. base_url=, timeout= (Sekunden pro Versuch) und max_retries= legen den Rest fest. BILLIONSEND_BASE_URL überschreibt die API-URL. AsyncBillionSend hat dieselben Ressourcen und Methoden: Setzen Sie vor jeden Aufruf await und schließen Sie den Client mit async with.
E-Mail senden
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"])
Jede Versand-Methode (emails.send, emails.batch, Antworten, Weiterleitungen, Postfach-Sendungen und Entwurfs-Sendungen) sendet einen Idempotency-Key. Ohne idempotency_key= denkt sich der Aufruf einen aus und verwendet ihn für seine eigenen Wiederholungen weiter. Ein erneuter Versuch nach einer abgebrochenen Verbindung sendet also nie doppelt. Übergeben Sie einen eigenen Schlüssel, etwa idempotency_key=f"welcome/{user_id}", um auf der sicheren Seite zu sein, wenn der sendende Code noch einmal laufen kann. Die API behält einen Schlüssel 24 Stunden lang.
Ein Postfach beantworten
Ein Agent wartet auf neue Mails, liest sie und antwortet im Thread:
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 # ein StreamGapEvent, siehe unten
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 ist der neue Teil der Nachricht ohne den zitierten Verlauf. Alles in einer empfangenen Nachricht hat ihr Absender geschrieben, behandeln Sie es also als nicht vertrauenswürdige Eingabe. Was das Postfach prüft, steht unter Agent-Sicherheit. Hält die Regel des Postfachs eine Antwort zur Freigabe durch eine Person zurück, antwortet reply mit dem Entwurf ("object": "inbox_draft") statt mit der gesendeten E-Mail.
Live-Ereignisse von Postfächern
client.inboxes.events.stream_inbox(inbox_id) folgt einem Postfach und client.inboxes.events.stream() jedem Postfach des Teams. types= beschränkt die Postfach-Ereignisse auf die genannten Namen. Der Stream liefert zwei Arten von Ereignissen:
InboxStreamEvent:id(die Position im Stream),event(etwainbox.email.received) unddata, ein Dict mittype,created_at,inbox_idunddata(der Payload des gleichnamigen Webhook-Ereignisses).StreamGapEvent:eventiststream.gapundidistNone. Der Stream wurde von einer Position fortgesetzt, die älter ist als die 24 Stunden, die die API nachspielt, es können also Ereignisse fehlen. Holen Sie sie über die Listen nach, zum Beispiel mitclient.inboxes.threads.list_all(inbox_id, read=False). Es kommt einmal pro Position.
Die API beendet jeden Stream nach einigen Minuten, und Verbindungen brechen ab. Der Stream verbindet sich mit Last-Event-ID von selbst neu, sodass kein Ereignis verloren geht. max_reconnects= begrenzt die fehlgeschlagenen Wiederverbindungen in Folge (standardmäßig 5, 0 schaltet das Wiederverbinden ab). Ein Fehler, den Wiederverbinden nicht beheben kann, etwa ein widerrufener Schlüssel, wird aus der Schleife ausgelöst. Der Stream eines einzelnen Postfachs endet nach dem Ereignis inbox.deleted oder inbox.expired dieses Postfachs. Um nach einem Neustart fortzusetzen, behalten Sie stream.last_event_id und übergeben es als last_event_id= zurück.
Webhooks verifizieren
from billionsend import WebhookVerificationError, verify_webhook
try:
event = verify_webhook(raw_body, request_headers, "whsec_...")
except WebhookVerificationError:
... # mit 400 antworten und die Zustellung ignorieren
print(event["type"], event["data"])
verify_webhook nimmt den Body genau so, wie er angekommen ist (Bytes oder Text, vor jedem JSON-Parsing), die Request-Header (jedes Mapping) und das Signing Secret des Endpunkts. Es prüft die Header webhook-id, webhook-timestamp und webhook-signature, wie Webhooks es beschreibt, akzeptiert während einer Rotation jedes der beiden Secrets, lehnt einen Zeitstempel ab, der mehr als tolerance= Sekunden (standardmäßig 300) von jetzt abweicht, und liefert das geparste Ereignis.
Fehler und Wiederholungsversuche
Ein fehlgeschlagener Aufruf löst eine Unterklasse von BillionSendError aus, mit status_code, name und message der API sowie request_id, der ID der Anfrage bei der API (ihr Header x-request-id):
| Status | Ausnahme |
|---|---|
| 400, 422 | ValidationError |
| 401 | AuthenticationError |
| 403 | PermissionDeniedError |
| 404 | NotFoundError |
| 409 | ConflictError |
| 429 | RateLimitError, mit retry_after in Sekunden |
| 5xx | APIError |
| keine Antwort | APIConnectionError oder seine Unterklasse APITimeoutError |
Anfragen, die sich gefahrlos wiederholen lassen (Lesezugriffe, PUT, Löschungen und jede Anfrage mit Idempotenzschlüssel), werden bei 429, bei 5xx, wenn keine Antwort zurückkam, und bei 409 concurrent_idempotent_requests wiederholt, standardmäßig zweimal. Die Wartezeit folgt retry-after, sonst wächst sie von einer halben Sekunde bis zu 8 Sekunden. Eine Antwort, die mehr als 60 Sekunden verlangt, wird sofort ausgelöst.
Listen
Listen-Methoden liefern eine Seite. Jede Cursor-Liste hat außerdem einen *_all-Iterator, der die nächsten Seiten nach und nach abruft:
for contact in client.contacts.list_all(limit=100):
print(contact["email"])
Mit AsyncBillionSend verwenden Sie async for.
Agent-Registrierung
signup = BillionSend().agent.signup({"human_email": "owner@acme.dev", "name": "Support agent"})
print(signup["inbox"]["email_address"])
Der Aufruf braucht keinen API-Schlüssel. Die Antwort enthält den neuen Schlüssel und das Postfach. Was ein nicht übernommenes Konto darf, steht unter Agent-Registrierung.