Wissensdatenbank

REST-API

Eine dokumentierte HTTP-API mit Schlüsseln, die sich ausstellen, in Scopes fassen und widerrufen lassen.

Details

Überall aktiv. Die API bedient 104 dokumentierte Operationen über 68 Pfade (E-Mails, Threads, Entwürfe, Labels, Kontakte, Audiences, Domains, Vorlagen, Regeln, Rollen, Mitglieder, Einstellungen, Kalender, Tracking, Webhooks und das Konto) hinter einem verbindlichen OpenAPI-3.1-Dokument, das Sie ohne Schlüssel unter GET /openapi.json lesen können. Über den Zugriff entscheidet der Workspace-Schlüssel, den Sie in den Einstellungen ausstellen.
Die Dauerhaftigkeit, auf die das früher gewartet hat, ist fertig. Ein Versand schreibt eine Zeile, bevor irgendetwas losgeschickt wird, mit einer öffentlichen id der Form msg_ gefolgt von 24 Hex-Zeichen, und GET /emails/{id} löst sie auf, zusammen mit /events für die Spur pro Empfänger und /tracking für Öffnungen und Klicks. Ein Idempotency-Key von 1–255 Zeichen wird gegen einen eindeutigen Index über den Key und Ihren API-Schlüssel zusammen beansprucht, sodass ein erneuter Versuch nach einem Timeout das erste Ergebnis mit Idempotency-Replayed: true zurückgibt, statt zweimal zu senden. Ein Versand mit Schlüssel antwortet mit 200, sobald er abgeschlossen ist, und mit 202, solange er noch in der Warteschlange steht oder geplant ist.
Schlüssel werden unter Einstellungen → API-Schlüssel erzeugt, mit Scopes versehen, rotiert und widerrufen. Jeder von der Konsole ausgestellte Schlüssel ist ein oe_live_-Schlüssel. Das Präfix oe_test_ versteht sowohl der Verifizierer als auch der Sendepfad, wo ein Versand im Testmodus aufgezeichnet und als gesendet beantwortet wird, ohne je einen Transport zu erreichen; erzeugen kann einen solchen Schlüssel aber noch nichts, und die Option anzubieten, bevor der No-op-Transport über dem Durable Object sitzt, würde Ihnen einen Testschlüssel geben, der tatsächlich zustellt. Ein Schlüssel trägt einen Sende-Scope von bis zu 25 ganzen Domains und 50 einzelnen Adressen, wobei eine ganze Domain auch später hinzugefügte Adressen abdeckt, ein optionales Ablaufdatum zwischen 1 und 3650 Tagen und optional eine Rolle. Die Rolle ist eine Obergrenze und keine zweite Berechtigung: GET /ping gibt sowohl die Scopes des Schlüssels als auch die Scopes zurück, die die Rolle ihm gelassen hat, sodass ein 403 für einen Scope, den Ihr Schlüssel ausdrücklich nennt, eine sichtbare Ursache hat. Widerrufen ist ein Update und kein Löschen, deshalb bekommt ein späterer Aufruf revoked_api_key zu hören, statt bloß an der Authentifizierung zu scheitern. Rotieren behält alles am Schlüssel außer dem Secret: die id, die Scopes, der Sende-Scope und die Anfragehistorie bleiben bestehen, das alte Secret stirbt in dem Moment, in dem das neue erzeugt wird, und ein Schlüssel mit keys:write kann sich über die API selbst rotieren. Dieselben Aktionen zum Auflisten, Rotieren, Widerrufen und Aktivieren gibt es auf dem MCP-Server für alle, deren Rolle Schlüssel verwalten darf.
Was tatsächlich fehlt: Die API hat keinen eigenen Upload-Endpunkt. Inline-Anhänge gehen als base64 unter einer Gesamtgrenze von 5 MB, und eine größere Datei wird gesendet, indem eine bereits im Workspace liegende Datei über ihre id benannt wird, die dann als Download-Link mitreist. Unzustellbarkeiten werden im Postfach behandelt und nicht im Sendeprotokoll: Ein Zustellbericht wird geparst, über die Message-ID dem Original zugeordnet, am Thread mit einem Label versehen und als Webhook email.bounced ausgeliefert, aber nichts schreibt in die Sendezeile zurück, deren status keinen Zustand bounced kennt; über GET /emails liest sich eine zurückgewiesene Nachricht daher weiterhin als sent. Mail, die aus dem Composer der App gesendet wurde, erscheint ebenfalls nicht in GET /emails, weil der Composer nicht über denselben Sendepfad schreibt.