Kennisbank

REST API

Een gedocumenteerde HTTP-API met sleutels die je kunt uitgeven, van scopes voorzien en intrekken.

Details

Overal aan. De API serveert 104 gedocumenteerde operaties verdeeld over 68 paden (e-mails, threads, concepten, labels, contacten, audiences, domeinen, templates, regels, rollen, leden, instellingen, agenda, tracking, webhooks en het account) achter een vastgelegd OpenAPI 3.1-document dat je zonder sleutel kunt lezen via GET /openapi.json. De toegang wordt bepaald door de workspace-sleutel die je in Instellingen uitgeeft.
De duurzaamheid waarop dit vroeger wachtte, is klaar. Een verzending schrijft een rij weg voordat er iets wordt verstuurd, met een publieke id in de vorm msg_ gevolgd door 24 hex-tekens, en GET /emails/{id} lost die op, samen met /events voor het spoor per ontvanger en /tracking voor opens en kliks. Een Idempotency-Key van 1–255 tekens wordt geclaimd tegen een unieke index op de sleutel en je API-sleutel samen, dus een nieuwe poging na een time-out geeft het eerste resultaat terug met Idempotency-Replayed: true in plaats van twee keer te versturen. Een verzending met sleutel antwoordt 200 zodra die is afgerond en 202 zolang die nog in de wachtrij staat of gepland is.
Sleutels worden in Instellingen → API-sleutels aangemaakt, van scopes voorzien, geroteerd en ingetrokken. Elke sleutel die de console uitgeeft is er een met oe_live_. Het voorvoegsel oe_test_ wordt begrepen door de verifier en door het verzendpad, waar een verzending in testmodus wordt vastgelegd en als verzonden beantwoord zonder ooit een transport te bereiken, maar er kan er nog geen worden aangemaakt: de optie aanbieden voordat het no-op-transport boven het Durable Object zit, zou je een testsleutel geven die echt aflevert. Een sleutel draagt een verzendscope van maximaal 25 hele domeinen en 50 losse adressen, waarbij een heel domein ook adressen dekt die er later aan worden toegevoegd, een optionele vervaltermijn tussen 1 en 3650 dagen, en eventueel een rol. De rol is een plafond en geen tweede toekenning: GET /ping geeft zowel de scopes op de sleutel terug als de scopes die de rol eraan overlaat, zodat een 403 voor een scope die je sleutel gewoon noemt een zichtbare oorzaak heeft. Intrekken is een update en geen verwijdering, dus een latere aanroep krijgt revoked_api_key te horen in plaats van simpelweg niet te kunnen authenticeren. Roteren behoudt alles aan de sleutel behalve het geheim: de id, de scopes, de verzendscope en de verzoekgeschiedenis lopen door, het oude geheim sterft op het moment dat het nieuwe wordt aangemaakt, en een sleutel met keys:write kan zichzelf via de API roteren. Dezelfde acties voor lijsten, roteren, intrekken en inschakelen staan op de MCP-server voor iedereen wiens rol sleutels mag beheren.
Wat er echt ontbreekt: de API heeft geen eigen upload-endpoint. Inline bijlagen gaan als base64 onder een totale limiet van 5 MB, en een groter bestand verstuur je door een bestand dat al in de workspace staat bij zijn id te noemen, dat vervolgens als downloadlink meereist. Bounces worden in de mailbox afgehandeld en niet in het verzendlogboek: een afleverrapport wordt geparseerd, via Message-ID aan het origineel gekoppeld, op de thread gelabeld en als email.bounced-webhook verstuurd, maar er wordt niets teruggeschreven naar de verzendrij, waarvan de status geen bounced-toestand kent, dus via GET /emails leest een gebouncet bericht nog steeds als verzonden. Mail die vanuit het opstelvenster van de app is verstuurd, verschijnt evenmin in GET /emails, omdat het opstelvenster niet via hetzelfde verzendpad wegschrijft.