SDK Python
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.
Le paquet billionsend est le client BillionSend pour Python. Il couvre toutes les opérations de la référence de l’API : 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 sur GitHub.
Installation
Python 3.11 ou plus récent est requis. Sa seule dépendance est httpx.
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
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 :
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 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 aux noms indiqués. Le flux produit deux sortes d’événements :
InboxStreamEvent:id(la position dans le flux),event(commeinbox.email.received) etdata, un dict avectype,created_at,inbox_idetdata(la charge utile de l’événement de webhook du même nom).StreamGapEvent:eventvautstream.gapetidvautNone. 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 exempleclient.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
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, 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 :
for contact in client.contacts.list_all(limit=100):
print(contact["email"])
Avec AsyncBillionSend, utilisez async for.
Inscription d’un agent
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 pour ce qu’un compte non réclamé peut faire.