---
title: Python-SDK
description: "E-Mails senden, Postfach bedienen, Webhooks verifizieren mit dem Paket billionsend, sync oder async: jede API-Operation, Wiederholungen, Idempotenzschlüssel."
ai:
  exclude: true
---

Das Paket `billionsend` ist der BillionSend-Client für Python. Es deckt jede Operation der [API-Referenz](/docs/de/api-reference) 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](https://github.com/billionsend/billionsend-python).

## Installation

Erfordert Python 3.11 oder neuer. Die einzige Abhängigkeit ist `httpx`.

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

```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"])
```

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:

```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  # 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](/docs/de/agent-safety). 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](/docs/de/inboxes) auf die genannten Namen. Der Stream liefert zwei Arten von Ereignissen:

- `InboxStreamEvent`: `id` (die Position im Stream), `event` (etwa `inbox.email.received`) und `data`, ein Dict mit `type`, `created_at`, `inbox_id` und `data` (der Payload des gleichnamigen Webhook-Ereignisses).
- `StreamGapEvent`: `event` ist `stream.gap` und `id` ist `None`. 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 mit `client.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

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

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

Mit `AsyncBillionSend` verwenden Sie `async for`.

## Agent-Registrierung

```python
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](/docs/de/agent-signup).
