Base de connaissances
API REST
Une API HTTP documentée avec des clés émissibles, limitables par scope et révocables.
Détails
- Active, partout. L'API sert 104 opérations documentées sur 68 chemins (emails, threads, brouillons, labels, contacts, audiences, domaines, modèles, règles, rôles, membres, paramètres, calendrier, suivi, webhooks et le compte) derrière un document OpenAPI 3.1 engageant que vous pouvez lire sans clé sur GET /openapi.json. L'accès est déterminé par la clé d'espace de travail que vous émettez dans les Paramètres.
- La durabilité que cela attendait autrefois est en place. Un envoi écrit une ligne avant que quoi que ce soit ne soit expédié, avec un identifiant public de la forme msg_ suivi de 24 caractères hexadécimaux, et GET /emails/{id} le résout, aux côtés de /events pour la trace par destinataire et de /tracking pour les ouvertures et les clics. Une Idempotency-Key de 1 à 255 caractères est revendiquée sur un index unique portant sur la clé et votre clé d'API ensemble : une nouvelle tentative après un dépassement de délai renvoie donc le premier résultat avec Idempotency-Replayed: true au lieu d'envoyer deux fois. Un envoi avec clé répond 200 une fois qu'il est établi et 202 tant qu'il est encore en file d'attente ou programmé.
- Les clés sont créées, limitées par scope, tournées et révoquées dans Paramètres → Clés d'API. Toute clé émise par la console est une clé oe_live_. Le préfixe oe_test_ est compris par le vérificateur et par le chemin d'envoi, où un envoi en mode test est enregistré et renvoyé comme envoyé sans jamais atteindre de transport, mais rien ne peut encore en créer une, et proposer l'option avant que le transport sans effet ne soit placé au-dessus du Durable Object vous donnerait une clé de test qui livre pour de vrai. Une clé porte un scope d'envoi allant jusqu'à 25 domaines entiers et 50 adresses uniques, où un domaine entier couvre aussi les adresses qui lui seront ajoutées plus tard, une expiration facultative entre 1 et 3650 jours, et éventuellement un rôle. Le rôle est un plafond plutôt qu'une seconde autorisation : GET /ping renvoie à la fois les scopes portés par la clé et ceux que le rôle lui a laissés, si bien qu'un 403 sur un scope que votre clé nomme explicitement a une cause visible. Révoquer est une mise à jour plutôt qu'une suppression : un appel ultérieur se voit donc répondre revoked_api_key au lieu d'échouer simplement à s'authentifier. Une rotation conserve tout de la clé sauf le secret : l'identifiant, les scopes, le scope d'envoi et l'historique des requêtes continuent, l'ancien secret meurt à l'instant où le nouveau est créé, et une clé portant keys:write peut se faire tourner elle-même via l'API. Les mêmes actions de liste, rotation, révocation et activation existent sur le serveur MCP pour quiconque a un rôle autorisé à gérer les clés.
- Ce qui manque vraiment : l'API n'a pas de point de terminaison d'upload propre. Les pièces jointes en ligne partent en base64 sous un plafond total de 5 MB, et un fichier plus gros s'envoie en nommant par son identifiant un fichier déjà présent dans l'espace de travail, qui voyage sous forme de lien de téléchargement. Les rebonds sont traités dans la boîte mail plutôt que dans le journal d'envoi : un rapport de livraison est analysé, rapproché de l'original par Message-ID, étiqueté sur le thread et poussé comme webhook email.bounced, mais rien n'est réécrit dans la ligne d'envoi, dont le statut n'a pas d'état bounced : via GET /emails, un message rejeté se lit donc toujours comme sent. Le courrier envoyé depuis la fenêtre de rédaction de l'application n'apparaît pas non plus dans GET /emails, car la fenêtre de rédaction n'écrit pas par le même chemin d'envoi.