Aller au contenu
Esc
↑↓naviguer↵ouvrir⌘Japerçu
Sur cette page

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 (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

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.

Cette page vous a-t-elle été utile ?