Guides pour les développeurs IA

La surface API de Bird est conçue pour les agents : une opération par outil, du JSON en entrée et en sortie, et des résultats vérifiables par la machine. Un agent fiable a tout de même besoin des bons patterns autour de lui. Ces cinq patterns couvrent les modes de défaillance qui cassent les intégrations d'agents : traiter l'acceptation comme une livraison, réessayer sans contexte, et analyser de la prose au lieu de la structure. Chaque pattern fonctionne de la même manière que votre agent pilote le serveur MCP ou le bird CLI. Les exemples ci-dessous utilisent l'e-mail, car c'est là que l'outillage autour d'un envoi est le plus complet, et les patterns s'appliquent à SMS et WhatsApp sans changement : le même 202 sur l'envoi, la même séquence d'événements accepté-puis-terminal, la même réponse d'erreur. La seule exception est le Pattern 3, dont les adresses magiques sont un sandbox e-mail.

Pattern 1 : Boucler une opération à la fois

Les outils de Bird sont volontairement granulaires : envoyer un message, récupérer un message, lister les domaines ou créer un endpoint de webhook. Chaque outil renvoie du JSON structuré dont les champs peuvent être vérifiés à l'étape suivante. Construisez la boucle de sorte que la condition de sortie de chaque étape provienne de la sortie de l'étape précédente :

Exemple de code

loop:
  result = run_tool(next_operation)        # one operation per call
  if result.ok: advance using result.data  # for example, the em_… ID or verified domain
  else: branch on the failure category     # see Pattern 4

Avec le CLI, la catégorie d'erreur est le code de sortie, donc le branchement ne nécessite aucune analyse de message. Consultez le tableau complet dans CLI :

Exemple de code

bird email get "$id" --format json > msg.json
case $? in
  0) jq .status msg.json ;;     # advance
  3) echo "wrong ID: fix the value instead of retrying" ;;
  4) bird auth login ;;          # recover, then re-run
esac

La granularité est l'essentiel : un agent capable de vérifier l'état entre les étapes se remet de n'importe quelle défaillance isolée ; un agent pilotant une méga-opération unique ne peut que tout recommencer.

Pattern 2 : Un envoi renvoie 202 ; le résultat arrive plus tard

POST un envoi et vous obtenez 202 Accepted avec un identifiant de message. Accepté signifie que Bird a pris le message en charge et que la livraison est en cours. Le résultat final arrive sous forme d'événements webhook : email.delivered quand le serveur du destinataire l'accepte, email.bounced quand la livraison échoue définitivement, email.complained, etc.

Un agent qui déclare le succès à 202 manque silencieusement chaque rebond. Structurez la tâche comme envoi-puis-attente à la place :

Exemple de code

send → 202 + em_… ID            # record the ID; delivery is still pending
await webhook event where data.email_id == em_… id:
  email.delivered → done
  email.bounced   → report failure with bounce_type / bounce_description

Corrélez sur email_id. Les payloads de webhook reprennent vos tags et métadonnées à côté des champs d'identité, donc votre propre contexte revient sans recherche supplémentaire. Les livraisons sont au-moins-une-fois et non ordonnées ; dédupliquez sur l'en-tête webhook-id et triez par le timestamp du payload. Si votre agent n'a pas de récepteur de webhook, interrogez le message avec GET (ou bird email get) jusqu'à ce que son statut se résolve. L'interrogation est plus lente, mais la relecture reste la source de vérité.

Pattern 3 : Utiliser le sandbox comme harnais de test

Pendant le développement de la boucle, utilisez les adresses magiques du sandbox e-mail sur messagebird.dev au lieu de vraies boîtes aux lettres. L'adresse détermine le résultat (delivered@ livre toujours, bounce@ produit toujours un hard-bounce, et complaint@ déclenche toujours une plainte). Tout le reste utilise le pipeline de production : le même 202, la même séquence d'événements, et les mêmes livraisons webhook signées, sans aucun indicateur marquant le message comme test.

Exemple de code

for address in [delivered@, bounce@, suppressed@] @messagebird.dev:
  send to address+run42@…                  # +label correlates the test case
  assert the expected terminal event arrives (delivered / bounced / rejected)

Le sandbox fournit des résultats déterministes, aucun risque de réputation, aucune écriture dans la liste de suppression, et des adresses réutilisables d'une exécution à l'autre. Un agent qui réussit la matrice du sandbox a exercé le chemin complet du Pattern 2 (envoi, attente et branchement) avant de toucher une vraie boîte de réception.

Pattern 4 : Récupérer grâce à la réponse d'erreur standard

Chaque erreur API de Bird a la même forme, donc un seul chemin de récupération fonctionne pour tous les endpoints :

Exemple de code

{
  "error": {
    "type": "validation_error",
    "code": "E04006",
    "name": "DomainNotVerified",
    "message": "The from address uses a domain that is not verified in this workspace.",
    "doc_url": "https://bird.com/docs/api/errors/E04006",
    "request_id": "req_01krdgeqcxet5s7t44vh8rt9mg"
  }
}

Chaque champ a un rôle dans la boucle. Branchez sur type/code (stable et lisible par la machine), affichez message à l'humain, et récupérez doc_url quand l'agent a besoin de la page pour cette erreur précise. L'URL renvoie du Markdown que l'agent peut lire. Journalisez request_id pour qu'un humain puisse le transmettre au support Bird. Ensuite, séparez les erreurs réessayables des erreurs de requête :

Exemple de code

4xx (except 429) → a request bug: fix the input, never retry as-is
429              → back off, then retry (Pattern 5)
5xx / timeout    → retry with the same Idempotency-Key (Pattern 5)

Le catalogue complet des codes se trouve sur la page des erreurs. Avec le CLI, la réponse d'erreur arrive sur stderr et le code de sortie la pré-classifie (voir le Pattern 1 et le tableau complet dans CLI). Un agent piloté par shell peut donc brancher avant d'analyser quoi que ce soit.

Pattern 5 : Réessayer en toute sécurité avec Idempotency-Key et Retry-After

Les réessais peuvent dupliquer le travail quand un envoi expire et que l'agent retente. Le support d'idempotence de Bird rend les réessais sûrs. Générez un Idempotency-Key par opération logique et réutilisez-le à chaque tentative :

Exemple de code

key = uuid()                                  # once per logical send
attempt with Idempotency-Key: key
on 5xx / timeout: backoff, retry with SAME key
on 2xx with Idempotency-Replay: true → the first attempt had succeeded; do not treat as a new send

L'en-tête de réponse Idempotency-Replay: true signale une relecture de la réponse originale, donc votre agent peut journaliser "recovered" au lieu de "sent twice". Les SDK Bird injectent automatiquement une clé sur chaque requête mutante, donc les agents basés sur SDK l'obtiennent gratuitement ; avec le CLI, passez --idempotency-key sur les mutations susceptibles d'être réessayées.

Un 429 signifie que l'agent doit ralentir. La réponse contient un en-tête Retry-After ; utilisez-le comme backoff minimum au lieu d'inventer un calendrier séparé :

Exemple de code

on 429: sleep max(Retry-After, backoff(attempt)); retry with the same key

Ne réessayez pas les autres réponses 4xx telles quelles. L'idempotence les met en cache et les rejoue parce que la même requête produit la même erreur. Corrigez la requête (Pattern 4) et utilisez une nouvelle clé ; réutiliser une clé avec un corps différent renvoie 409 IdempotencyKeyReuse.

Étapes suivantes

Serveur MCP : la surface d'outils que ces patterns pilotent, hébergée sur mcp.bird.com ou exécutée localement avec le CLI
CLI pour agents : les mêmes opérations pour les agents capables d'utiliser un shell
Webhooks et événements : sémantique de livraison, signatures, et le catalogue d'événements derrière le Pattern 2
Idempotence : sémantique de relecture et modes de défaillance derrière le Pattern 5
Erreurs : la réponse d'erreur et le catalogue complet des codes d'erreur
Sandbox e-mail : la matrice d'adresses magiques derrière le Pattern 3

Ressources associées

Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.

Comprendre le conceptHow do I use Bird from a low-code tool like n8n or Zapier?Explorer la fonctionnalitéWorkflow automation Suivre le parcours d'apprentissageBuild with AI agents

Obtenir un guide d'implémentation