AI-buildergidsen

Het API-oppervlak van Bird is agent-vormig: één operatie per tool, JSON in en uit, en machinaal controleerbare resultaten. Een betrouwbare agent heeft nog steeds de juiste patronen eromheen nodig. Deze vijf patronen dekken de faalscenario's die agentintegraties breken: acceptatie als aflevering beschouwen, opnieuw proberen zonder context, en proza parsen in plaats van structuur. Elk patroon werkt hetzelfde, of je agent nu de MCP-server of de bird CLI aanstuurt. De voorbeelden hieronder gebruiken e-mail, omdat de tooling rond een verzending daar het diepst is, en de patronen gelden ongewijzigd voor SMS en WhatsApp: dezelfde 202 op de verzending, dezelfde accepted-then-terminal-eventreeks, hetzelfde foutantwoord. De enige uitzondering is Patroon 3, waarvan de magic-adressen een e-mailsandbox zijn.

Patroon 1: Voer één operatie tegelijk uit in een loop

De tools van Bird zijn bewust fijnmazig: een bericht versturen, een bericht ophalen, domeinen opvragen of een webhook-endpoint aanmaken. Elke tool retourneert gestructureerde JSON waarvan de velden in de volgende stap gecontroleerd kunnen worden. Bouw de loop zo dat de exitconditie van elke stap voortkomt uit de output van de vorige stap:

Codevoorbeeld

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

Met de CLI is de foutcategorie de exitcode, dus de vertakking heeft geen berichtparsing nodig. Bekijk de volledige tabel in CLI:

Codevoorbeeld

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

De fijnmazigheid is het hele punt: een agent die tussen stappen de status kan controleren, herstelt van elke afzonderlijke fout; een agent die één mega-operatie aanstuurt, kan alleen opnieuw beginnen.

Patroon 2: Een verzending retourneert 202; het resultaat komt later

POST een verzending en je krijgt 202 Accepted met een bericht-ID. Accepted betekent dat Bird het bericht heeft aangenomen en dat aflevering in behandeling is. Het uiteindelijke resultaat komt binnen als webhook-events: email.delivered wanneer de server van de ontvanger het accepteert, email.bounced wanneer aflevering definitief mislukt, email.complained, enzovoort.

Een agent die bij 202 succes meldt, mist stilzwijgend elke bounce. Structureer de taak als verzend-dan-wacht:

Codevoorbeeld

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

Correleer op email_id. Webhook-payloads bevatten je tags en metadata naast de identiteitsvelden, zodat je eigen context terugkomt zonder een extra lookup. Afleveringen zijn at-least-once en ongeordend; dedupliseer op de webhook-id-header en sorteer op de payload-timestamp. Als je agent geen webhook-ontvanger heeft, poll dan het bericht met GET (of bird email get) totdat de status definitief is. Polling is langzamer, maar de teruggelezen waarde blijft de bron van waarheid.

Patroon 3: Gebruik de sandbox als testharnas

Gebruik tijdens het ontwikkelen van de loop de magic-adressen van de mailsandbox op messagebird.dev in plaats van echte mailboxen. Het adres bepaalt het resultaat (delivered@ levert altijd af, bounce@ geeft altijd een hard bounce, en complaint@ genereert altijd een klacht). Al het andere gebruikt de productiepipeline: dezelfde 202, eventreeks en ondertekende webhook-afleveringen, zonder een vlag die het bericht als test markeert.

Codevoorbeeld

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)

De sandbox biedt deterministische resultaten, geen reputatierisico, geen schrijfacties naar de suppressielijst en herbruikbare adressen over runs heen. Een agent die de sandboxmatrix doorstaat, heeft het volledige Patroon 2-pad (verzenden, wachten en vertakken) doorlopen voordat er een echte inbox wordt aangeraakt.

Patroon 4: Herstel aan de hand van het standaard foutantwoord

Elke Bird API-fout heeft dezelfde vorm, dus één foutherstelpad werkt voor alle endpoints:

Codevoorbeeld

{
  "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"
  }
}

Elk veld heeft een rol in de loop. Vertaak op type/code (stabiel en machineleesbaar), toon message aan de mens, en haal doc_url op wanneer de agent de pagina voor die specifieke fout nodig heeft. De URL verwijst naar Markdown die de agent kan lezen. Log request_id zodat een mens het kan doorgeven aan Bird-support. Scheid daarna opnieuw-probeerbare fouten van requestfouten:

Codevoorbeeld

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)

De volledige codecatalogus staat op de foutenpagina. Met de CLI komt het foutantwoord binnen op stderr en classificeert de exitcode het vooraf (zie Patroon 1 en de volledige tabel in CLI). Een shell-sturende agent kan dus vertakken zonder iets te parsen.

Patroon 5: Veilig opnieuw proberen met Idempotency-Key en Retry-After

Opnieuw proberen kan werk dupliceren wanneer een verzending een time-out geeft en de agent het nogmaals probeert. De idempotency-ondersteuning van Bird maakt opnieuw proberen veilig. Genereer één Idempotency-Key per logische operatie en hergebruik deze bij elke poging:

Codevoorbeeld

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

De Idempotency-Replay: true-responseheader markeert een replay van het oorspronkelijke antwoord, zodat je agent "recovered" kan loggen in plaats van "sent twice". De Bird-SDK's injecteren automatisch een key bij elk muterend request, dus SDK-gebaseerde agents krijgen dit gratis; met de CLI geef je --idempotency-key mee bij mutaties die mogelijk opnieuw geprobeerd worden.

Een 429 betekent dat de agent moet vertragen. Het antwoord bevat een Retry-After-header; gebruik die als minimale backoff in plaats van een apart schema te verzinnen:

Codevoorbeeld

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

Probeer andere 4xx-antwoorden niet ongewijzigd opnieuw. Idempotency cachet en herhaalt ze omdat hetzelfde request dezelfde fout oplevert. Herstel het request (Patroon 4) en gebruik een nieuwe key; een key hergebruiken met een andere body retourneert 409 IdempotencyKeyReuse.

Volgende stappen

MCP-server: het tooloppervlak dat deze patronen aansturen, gehost op mcp.bird.com of lokaal gedraaid met de CLI
CLI voor agents: dezelfde operaties voor shell-capabele agents
Webhooks & events: afleveringssemantiek, ondertekeningen en de eventcatalogus achter Patroon 2
Idempotency: replaysemantiek en faalscenario's achter Patroon 5
Fouten: het foutantwoord en de volledige foutcodecatalogus
Mailsandbox: de magic-adresmatrix achter Patroon 3

Gerelateerde bronnen

Ga verder met de documentatie, gidsen en voorbeelden voor dit onderwerp. De bronnen zijn in het Engels.

Begrijp het conceptHow do I use Bird from a low-code tool like n8n or Zapier?Ontdek de mogelijkheidWorkflow automation Volg het leerpadBuild with AI agents

Ontvang een implementatieoverzicht