Sign inGet Started
Jetzt starten
Anleitungen
API-Referenz
SDKs
CLI
Wissensdatenbank
Changelog

Leitfäden für AI-Builder

Die API-Oberfläche von Bird ist auf Agents zugeschnitten: eine Operation pro Tool, JSON ein und aus, und maschinenprüfbare Ergebnisse. Ein zuverlässiger Agent braucht dennoch die richtigen Muster drumherum. Diese fünf Muster decken die Fehlermodi ab, die Agent-Integrationen scheitern lassen: Annahme als Zustellung werten, ohne Kontext erneut versuchen und Prosa statt Struktur parsen. Jedes Muster funktioniert gleich, egal ob Ihr Agent den MCP-Server oder die bird CLI ansteuert. Die Beispiele unten verwenden E-Mail, weil dort das Tooling rund um einen Versand am umfangreichsten ist, und die Muster gelten für SMS und WhatsApp unverändert: dasselbe 202 beim Versand, dieselbe Accepted-then-Terminal-Eventsequenz, dieselbe Fehlerantwort. Die einzige Ausnahme ist Muster 3, dessen Magic-Adressen eine E-Mail-Sandbox sind.

Muster 1: Eine Operation pro Schleifendurchlauf

Die Tools von Bird sind bewusst granular: eine Nachricht senden, eine Nachricht abrufen, Domains auflisten oder einen Webhook-Endpoint erstellen. Jedes Tool gibt strukturiertes JSON zurück, dessen Felder der nächste Schritt prüfen kann. Bauen Sie die Schleife so, dass die Abbruchbedingung jedes Schritts aus der Ausgabe des vorherigen Schritts stammt:
Codebeispiel
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
Mit der CLI ist die Fehlerkategorie der Exit-Code, sodass die Verzweigung kein Message-Parsing braucht. Die vollständige Tabelle finden Sie unter CLI:
Codebeispiel
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
Die Granularität ist der Punkt: Ein Agent, der zwischen den Schritten den Zustand prüfen kann, erholt sich von jedem einzelnen Fehler; ein Agent, der eine einzige Mega-Operation ausführt, kann nur von vorn anfangen.

Muster 2: Ein Versand gibt 202 zurück; das Ergebnis kommt später

Senden Sie POST ab und Sie erhalten 202 Accepted mit einer Message-ID. Accepted bedeutet, dass Bird die Nachricht angenommen hat und die Zustellung aussteht. Das endgültige Ergebnis kommt als Webhook-Events: email.delivered, wenn der Server des Empfängers sie annimmt, email.bounced, wenn die Zustellung endgültig fehlschlägt, email.complained und so weiter.
Ein Agent, der bei 202 Erfolg meldet, übersieht stillschweigend jeden Bounce. Strukturieren Sie die Aufgabe stattdessen als Senden-dann-Warten:
Codebeispiel
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
Korrelieren Sie über email_id. Webhook-Payloads enthalten Ihre Tags und Metadaten neben den Identitätsfeldern, sodass Ihr eigener Kontext ohne zusätzlichen Lookup zurückkommt. Zustellungen erfolgen at-least-once und ungeordnet; deduplizieren Sie über den webhook-id-Header und sortieren Sie nach dem Payload-Feld timestamp. Wenn Ihr Agent keinen Webhook-Empfänger hat, pollen Sie die Nachricht mit GET (oder bird email get), bis sich ihr Status auflöst. Polling ist langsamer, aber der Read-back bleibt die Quelle der Wahrheit.

Muster 3: Nutzen Sie die Sandbox als Test-Harness

Verwenden Sie während der Entwicklung der Schleife die Magic-Adressen der Mail-Sandbox auf messagebird.dev anstelle echter Postfächer. Die Adresse bestimmt das Ergebnis (delivered@ stellt immer zu, bounce@ erzeugt immer einen Hard-Bounce und complaint@ löst immer eine Beschwerde aus). Alles andere nutzt die Produktions-Pipeline: dasselbe 202, dieselbe Eventsequenz und signierte Webhook-Zustellungen, ohne Flag, das die Nachricht als Test kennzeichnet.
Codebeispiel
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)
Die Sandbox liefert deterministische Ergebnisse, kein Reputationsrisiko, keine Einträge in Suppressionslisten und wiederverwendbare Adressen über Durchläufe hinweg. Ein Agent, der die Sandbox-Matrix besteht, hat den vollständigen Pfad aus Muster 2 (Senden, Warten und Verzweigen) durchlaufen, bevor er ein echtes Postfach berührt.

Muster 4: Fehler gegen die Standard-Fehlerantwort behandeln

Jeder Bird-API-Fehler hat dieselbe Struktur, sodass ein einzelner Fehlerbehandlungspfad über alle Endpoints hinweg funktioniert:
Codebeispiel
{
  "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"
  }
}
Jedes Feld hat eine Aufgabe in der Schleife. Verzweigen Sie auf type/code (stabil und maschinenlesbar), zeigen Sie message dem Menschen und rufen Sie doc_url ab, wenn der Agent die Seite für genau diesen Fehler braucht. Die URL löst zu Markdown auf, das der Agent lesen kann. Loggen Sie request_id, damit ein Mensch sie an den Bird-Support geben kann. Trennen Sie dann wiederholbare Fehler von Request-Fehlern:
Codebeispiel
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)
Den vollständigen Code-Katalog finden Sie auf der Fehlerseite. Mit der CLI kommt die Fehlerantwort auf stderr und der Exit-Code klassifiziert sie vor (siehe Muster 1 und die vollständige Tabelle unter CLI). Ein Shell-steuernder Agent kann daher verzweigen, bevor er irgendetwas parst.

Muster 5: Sicher erneut versuchen mit Idempotency-Key und Retry-After

Wiederholungen können Arbeit duplizieren, wenn ein Versand ein Timeout hat und der Agent es erneut versucht. Die Idempotenz-Unterstützung von Bird macht Wiederholungen sicher. Generieren Sie einen Idempotency-Key pro logische Operation und verwenden Sie ihn bei jedem Versuch erneut:
Codebeispiel
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
Der Idempotency-Replay: true-Response-Header kennzeichnet eine Wiedergabe der ursprünglichen Antwort, sodass Ihr Agent "recovered" statt "sent twice" loggen kann. Die Bird-SDKs injizieren bei jedem mutierenden Request automatisch einen Key, sodass SDK-basierte Agents dies kostenlos erhalten; mit der CLI übergeben Sie --idempotency-key bei Mutationen, die wiederholt werden könnten.
Ein 429 bedeutet, dass der Agent drosseln muss. Die Antwort enthält einen Retry-After-Header; verwenden Sie ihn als minimalen Backoff, statt einen eigenen Zeitplan zu erfinden:
Codebeispiel
on 429: sleep max(Retry-After, backoff(attempt)); retry with the same key
Wiederholen Sie andere 4xx-Antworten nicht unverändert. Idempotenz speichert und wiederholt sie, weil derselbe Request denselben Fehler erzeugt. Beheben Sie den Request (Muster 4) und verwenden Sie einen neuen Key; ein Key mit einem anderen Body gibt 409 IdempotencyKeyReuse zurück.

Nächste Schritte

  • MCP-Server: die Tool-Oberfläche, die diese Muster ansteuern, gehostet unter mcp.bird.com oder lokal ausgeführt mit der CLI
  • CLI für Agents: dieselben Operationen für Shell-fähige Agents
  • Webhooks & Events: Zustellsemantik, Signaturen und der Event-Katalog hinter Muster 2
  • Idempotenz: Wiedergabesemantik und Fehlermodi hinter Muster 5
  • Fehler: die Fehlerantwort und der vollständige Fehlercode-Katalog
  • Mail-Sandbox: die Magic-Address-Matrix hinter Muster 3

Verwandte Ressourcen

Weiter mit der Dokumentation, Anleitungen und Beispielen zu diesem Thema. Die Ressourcen sind auf Englisch.

Das Konzept verstehenHow do I use Bird from a low-code tool like n8n or Zapier?Die Funktion erkundenWorkflow automationDem Lernpfad folgenBuild with AI agents
Implementierungs-Briefing erhalten