---
title: SDK Python
description: "Envoyez des e-mails, gérez une boîte de réception et vérifiez des webhooks en Python, synchrone ou asynchrone, avec billionsend : toute l'API et l'idempotence."
ai:
  exclude: true
---

Le paquet `billionsend` est le client BillionSend pour Python. Il couvre toutes les opérations de la [référence de l'API](/docs/fr/api-reference) : envoi, domaines, contacts, campagnes, templates, webhooks, boîtes de réception avec leurs conversations et brouillons, événements de boîte de réception en direct et inscription d'agents. Ses types de requête et de réponse viennent du document OpenAPI de l'API. Le code source est [billionsend/billionsend-python](https://github.com/billionsend/billionsend-python) sur GitHub.

## Installation

Python 3.11 ou plus récent est requis. Sa seule dépendance est `httpx`.

```sh
pip install billionsend
```

## Authentification

`BillionSend()` lit la clé API dans `BILLIONSEND_API_KEY` ; `BillionSend("bs_...")` la prend directement. `base_url=`, `timeout=` (secondes par tentative) et `max_retries=` règlent le reste ; `BILLIONSEND_BASE_URL` remplace l'URL de l'API. `AsyncBillionSend` a les mêmes ressources et les mêmes méthodes ; faites un `await` sur chaque appel et utilisez `async with` pour le fermer.

## Envoyer un e-mail

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

Chaque méthode d'envoi (`emails.send`, `emails.batch`, réponses, transferts, envois depuis une boîte de réception et envois de brouillons) envoie une `Idempotency-Key`. Sans `idempotency_key=`, l'appel en fabrique une et la réutilise pour ses propres nouvelles tentatives : une nouvelle tentative après une connexion coupée n'envoie donc jamais deux fois. Passez votre propre clé, comme `idempotency_key=f"welcome/{user_id}"`, pour rester protégé lorsque le code qui envoie peut s'exécuter de nouveau ; l'API conserve une clé pendant 24 heures.

## Répondre depuis une boîte de réception

Un agent attend du nouveau courrier, le lit et répond dans le fil :

```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  # 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` est la partie nouvelle du message, sans l'historique cité. Tout ce que contient un message reçu a été écrit par son expéditeur : traitez-le comme une entrée non fiable ; [Sécurité des agents](/docs/fr/agent-safety) décrit ce que la boîte de réception filtre. Lorsque les règles de la boîte retiennent une réponse pour qu'une personne l'approuve, `reply` répond avec le brouillon (`"object": "inbox_draft"`) au lieu de l'e-mail envoyé.

## Événements de boîte de réception en direct

`client.inboxes.events.stream_inbox(inbox_id)` suit une boîte et `client.inboxes.events.stream()` toutes les boîtes de l'équipe ; `types=` limite les [événements de boîte de réception](/docs/fr/inboxes) aux noms indiqués. Le flux produit deux sortes d'événements :

- `InboxStreamEvent` : `id` (la position dans le flux), `event` (comme `inbox.email.received`) et `data`, un dict avec `type`, `created_at`, `inbox_id` et `data` (la charge utile de l'événement de webhook du même nom).
- `StreamGapEvent` : `event` vaut `stream.gap` et `id` vaut `None`. Le flux a repris à une position plus ancienne que les 24 heures que l'API rejoue, donc des événements peuvent manquer ; rattrapez-vous avec les listes, par exemple `client.inboxes.threads.list_all(inbox_id, read=False)`. Il arrive une fois par position.

L'API termine chaque flux au bout de quelques minutes et les connexions tombent ; le flux se reconnecte seul avec `Last-Event-ID`, donc aucun événement n'est perdu. `max_reconnects=` borne les échecs de reconnexion consécutifs (5 par défaut, `0` désactive la reconnexion). Une erreur que la reconnexion ne peut pas corriger, comme une clé révoquée, est levée depuis la boucle. Le flux d'une seule boîte se termine après l'événement `inbox.deleted` ou `inbox.expired` de cette boîte. Pour reprendre après un redémarrage, conservez `stream.last_event_id` et repassez-le avec `last_event_id=`.

## Vérifier les 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` prend le corps exactement tel qu'il a été reçu (octets ou texte, avant toute analyse JSON), les en-têtes de la requête (n'importe quel mapping) et le secret de signature de l'endpoint. Il vérifie les en-têtes `webhook-id`, `webhook-timestamp` et `webhook-signature` comme le décrit la page [Webhooks](/docs/fr/concepts/webhooks), accepte l'un ou l'autre secret pendant une rotation, refuse un horodatage éloigné de plus de `tolerance=` secondes (300 par défaut) de l'heure actuelle et renvoie l'événement analysé.

## Erreurs et nouvelles tentatives

Un appel en échec lève une sous-classe de `BillionSendError` avec le `status_code`, le `name` et le `message` de l'API, ainsi que `request_id`, l'identifiant de la requête côté API (son en-tête `x-request-id`) :

| Statut | Exception |
| --- | --- |
| 400, 422 | `ValidationError` |
| 401 | `AuthenticationError` |
| 403 | `PermissionDeniedError` |
| 404 | `NotFoundError` |
| 409 | `ConflictError` |
| 429 | `RateLimitError`, avec `retry_after` en secondes |
| 5xx | `APIError` |
| aucune réponse | `APIConnectionError`, ou sa sous-classe `APITimeoutError` |

Les requêtes sans danger à répéter (lectures, `PUT`, suppressions et toute requête portant une clé d'idempotence) sont retentées, deux fois par défaut, sur 429, sur 5xx, lorsqu'aucune réponse n'est revenue, et sur 409 `concurrent_idempotent_requests`. L'attente suit `retry-after`, sinon elle augmente progressivement d'une demi-seconde jusqu'à 8 secondes ; une réponse qui demande plus de 60 secondes est levée aussitôt.

## Listes

Les méthodes de liste renvoient une page. Chaque liste à curseur a aussi un itérateur `*_all` qui récupère les pages suivantes au fur et à mesure :

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

Avec `AsyncBillionSend`, utilisez `async for`.

## Inscription d'un agent

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

L'appel n'a pas besoin de clé API ; la réponse contient la nouvelle clé et la boîte de réception. Voir [Inscription d'un agent](/docs/fr/agent-signup) pour ce qu'un compte non réclamé peut faire.
