Base de coneixement

API REST

Una API HTTP documentada amb claus que es poden emetre, limitar per àmbits i revocar.

Detalls

Activa, a tot arreu. L'API ofereix 104 operacions documentades repartides en 68 camins (correus, converses, esborranys, etiquetes, contactes, audiències, dominis, plantilles, regles, rols, membres, configuració, calendari, seguiment, webhooks i el compte) darrere d'un document OpenAPI 3.1 compromès que podeu llegir sense clau a GET /openapi.json. L'accés el decideix la clau d'espai de treball que emeteu a Configuració.
La durabilitat que això esperava ja està feta. Un enviament escriu una fila abans que res es despatxi, amb un id públic de la forma msg_ seguit de 24 caràcters hexadecimals, i GET /emails/{id} el resol, juntament amb /events per al rastre per destinatari i /tracking per a obertures i clics. Una Idempotency-Key d'1 a 255 caràcters es reclama contra un índex únic sobre la clau i la vostra clau d'API alhora, de manera que un reintent després d'un temps d'espera esgotat retorna el primer resultat amb Idempotency-Replayed: true en comptes d'enviar dues vegades. Un enviament amb clau respon 200 un cop s'ha assentat i 202 mentre encara està en cua o programat.
Les claus s'encunyen, es limiten per àmbits, es roten i es revoquen a Configuració → Claus d'API. Totes les claus que emet la consola són oe_live_. El prefix oe_test_ l'entenen el verificador i el camí d'enviament, on un enviament en mode de prova es registra i es respon com a enviat sense arribar mai a un transport, però encara no hi ha res que en pugui encunyar una, i oferir l'opció abans que el transport nul se situï per sobre del Durable Object us donaria una clau de prova que lliura de debò. Una clau porta un àmbit d'enviament de fins a 25 dominis sencers i 50 adreces individuals, on un domini sencer cobreix també les adreces que s'hi afegeixin més endavant, una caducitat opcional d'entre 1 i 3650 dies i, opcionalment, un rol. El rol és un sostre i no pas una segona concessió: GET /ping retorna tant els àmbits de la clau com els àmbits que el rol li ha deixat, de manera que un 403 per a un àmbit que la vostra clau anomena clarament té una causa visible. Revocar és una actualització i no pas una supressió, així que a una crida posterior se li diu revoked_api_key en comptes de fallar simplement en autenticar-se. Rotar conserva tot allò de la clau excepte el secret: l'id, els àmbits, l'àmbit d'enviament i l'historial de sol·licituds continuen, el secret antic mor l'instant que s'encunya el nou, i una clau que tingui keys:write es pot rotar a si mateixa per l'API. Les mateixes accions de llistar, rotar, revocar i habilitar són al servidor MCP per a qualsevol persona el rol de la qual pugui gestionar claus.
El que falta de debò: l'API no té cap punt final de pujada propi. Els fitxers adjunts en línia van com a base64 amb un límit total de 5 MB, i un fitxer més gran s'envia indicant per id un fitxer que ja és a l'espai de treball, que viatja com a enllaç de descàrrega. Els rebots es gestionen a la bústia i no pas al registre d'enviaments: un informe de lliurament s'analitza, es fa coincidir amb l'original pel Message-ID, s'etiqueta a la conversa i s'emet com a webhook email.bounced, però no s'escriu res de tornada a la fila d'enviament, l'estat de la qual no té cap valor de rebotat, de manera que a través de GET /emails un missatge rebotat continua constant com a enviat. El correu enviat des del redactor de l'aplicació tampoc no apareix a GET /emails, perquè el redactor no escriu pel mateix camí d'enviament.