SDK
Lister et récupérer
`emails.list`, `emails.listAll`, `emails.iterate`, `emails.get` et `emails.listEvents`.
emails.list
const first = await openemail.emails.list({ status: ['queued', 'scheduled'], from: '[email protected]', limit: 50,}) const second = first.nextCursor ? await openemail.emails.list({ status: ['queued', 'scheduled'], limit: 50, cursor: first.nextCursor }) : nullUne page est { items, hasMore, nextCursor }. Renvoyez nextCursor comme cursor, avec les mêmes filtres, pour obtenir la page suivante.
emails.iterate et emails.listAll
for await (const email of openemail.emails.iterate({ status: 'failed' })) { console.error(email.id, email.lastError)} const failures = await openemail.emails.listAll({ status: 'failed', from: '[email protected]' })Les deux suivent nextCursor pour vous. iterate ne récupère une page que lorsque la boucle l'atteint, donc en sortir arrête les requêtes, tandis que listAll parcourt toutes les pages avant de se résoudre en un seul array : donnez-lui un filtre qui se termine. Pagination par keyset dans les deux cas : un message qui arrive en cours d'itération ne peut donc pas faire sauter une ligne, comme le ferait un offset.
emails.get et emails.listEvents
const email = await openemail.emails.get('msg_…')console.log(email.status, email.recipients) const events = await openemail.emails.listEvents('msg_…')for (const event of events) console.log(event.type, event.createdAt)get est le seul appel qui renvoie recipients, une ligne par adresse. Une liste de cinquante messages portant chacun ses destinataires, c'est une page de rapport que personne n'a demandée.
Paramètres
statusEmailStatus | EmailStatus[]- Un statut ou plusieurs (`queued`, `scheduled`, `sending`, `sent`, `partial`, `cancelled`, `failed`), la correspondance portant sur n'importe lequel de ceux donnés. Le SDK envoie un array sous la forme d'une seule valeur séparée par des virgules, car le serveur découpe sur les virgules ; une valeur hors de cet ensemble donne un 422 qui nomme l'inconnue.
fromstring- Correspondance exacte sur l'adresse d'expédition telle qu'elle a été enregistrée, c'est-à-dire le `addr@host` nu en minuscules. La ligne est écrite sans aucun nom d'affichage : une angle-addr telle que `Acme <[email protected]>` ne correspond donc à rien. Votre valeur est passée en minuscules avant comparaison, et il s'agit d'une égalité, pas d'une correspondance de préfixe ou de domaine.
limitnumber- Nombre de lignes dans cette page, de 1 à 100, 25 par défaut. Une valeur hors de cette plage est refusée par un 422 plutôt que ramenée aux bornes.
cursorstring- Un id de message (`msg_…`) à partir duquel paginer. Keyset plutôt qu'offset : les lignes renvoyées sont strictement plus anciennes que le `createdAt` de ce message, si bien que des envois arrivant en cours de pagination ne peuvent pas faire passer une ligne devant vous. Un id qui ne désigne aucun message de ce workspace donne un 400.
Réponse : Page<EmailResource>
itemsEmailResource[]- Une page de messages, du plus récent au plus ancien selon `createdAt`, extraite de l'enveloppe `data` de l'API. Les lignes de liste ne portent jamais le détail `recipients` par adresse. Il est sur `get`.
hasMoreboolean- Indique si d'autres lignes correspondent au filtre au-delà de cette page. Déterminé en récupérant une ligne de plus que `limit`, et non par une seconde requête de comptage.
nextCursorstring | null- L'id à renvoyer comme `cursor`, et null sur la dernière page. `iterate` et `listAll` s'arrêtent quand il vaut null ou que `hasMore` est false, car une page qui annonce d'autres résultats sans nommer de cursor tournerait en boucle sans fin.
items[].object'email'- Toujours `'email'` sur une ligne de cette liste.
items[].idstring- L'id propre à cette API, `msg_…`. C'est ce que prend tout autre point de terminaison emails, et ce qu'un cursor désigne.
items[].statusEmailStatus- Où en est le message dans sa vie. `partial` est un état à part entière et non une variante de failed : certains destinataires l'ont reçu et on ne peut pas le leur reprendre, réessayer serait donc une erreur.
items[].modeApiKeyMode- `live` ou `test`, repris de la clé qui l'a envoyé. Un envoi de test est enregistré ici et jamais transmis.
items[].fromstring- L'adresse sous laquelle l'envoi a été autorisé, stockée nue et en minuscules : un nom d'affichage donné sur `from` part bien sur le réseau mais n'est pas conservé ici. Une simple string plutôt qu'un object, car c'est l'identité qui a été autorisée : une adresse hors de la portée d'envoi d'une clé, ni sur un domaine qu'elle détient ni nommée sur elle, est refusée par un 403, jamais remplacée en silence par une adresse autorisée.
items[].subjectstring | null- L'objet tel que stocké. Null sur un message enregistré sans objet.
items[].messageIdstring | null- Le Message-ID RFC 5322, pas notre id. Null tant que le MIME n'existe pas, et réécrit par le service d'envoi au départ : un bounce ou un DSN ultérieur porte donc un id différent et se corrèle plutôt sur `items[].id`.
items[].threadIdstring | null- Le thread auquel ce message appartient, quand un thread a été donné ou attribué. Null sinon.
items[].transportEmailTransport | (string & {}) | null- Par où les octets sont partis. Null jusqu'à l'expédition, et typé ouvert pour qu'un transport que ce SDK ne nomme pas encore ne soit pas un changement cassant : des enregistrements stockés peuvent encore en nommer qui ne sont plus utilisés.
items[].attemptsnumber- Combien de tentatives d'expédition le message a connues, 0 avant la première.
items[].lastErrorstring | null- La dernière erreur d'expédition, rédigée pour un humain. Null tant que rien n'a échoué.
items[].scheduledAtstring | null- Quand le message doit partir, sous forme d'instant ISO-8601. Null uniquement sur un envoi immédiat sans fenêtre d'annulation : une fenêtre n'est rien d'autre qu'un court délai, donc `cancellableForSeconds` renseigne ce champ lui aussi, sur une ligne dont le `status` est `queued` et non `scheduled`.
items[].cancellableUntilstring | null- L'instant où le message doit partir, portant la même valeur que `scheduledAt` sur tout envoi différé et null sur un envoi qui ne l'était pas. C'est un timestamp à afficher, pas le test que fait le serveur : `cancel` se branche sur `status` et n'arrête un message que tant qu'il est encore `queued` ou `scheduled`.
items[].sentAtstring | null- Quand il est parti. Null tant que l'expédition n'est pas terminée, ce qui explique que le champ sur lequel se brancher soit `status` et non celui-ci.
items[].tagsRecord<string, string>- Les libellés fournis à l'envoi, renvoyés tels quels et jamais interprétés. Toujours un object (`{}` quand aucun n'a été défini, jamais null), et seulement renvoyés : ce point de terminaison filtre sur `status` et `from`, un tag est donc une chose à lire sur un message, pas un moyen d'en retrouver un.
items[].sourceEmailSource- Quelle surface a demandé l'envoi : `composer`, `api`, `mcp`, `ai` ou `queue`. `api`, c'est ce client.
items[].createdAtstring- Quand l'enregistrement d'envoi a été écrit, c'est-à-dire avant l'expédition. C'est le champ sur lequel la liste est triée et celui auquel un cursor est comparé.
items[].trackingEmailTrackingSummary- Le résumé d'engagement, présent uniquement sur une ligne dont le message a été suivi, absent sinon. L'absence répond à « ce message a-t-il été suivi ? », là où `openCount: 0` se lirait comme « personne ne l'a ouvert ».
items[].tracking.opensboolean- Indique si ce message est parti avec un pixel. Ce qui a été appliqué à ce message, pas ce que dit aujourd'hui le réglage du compte.
items[].tracking.clicksboolean- Indique si les liens de ce message ont été réécrits. False quand le corps n'avait aucun lien à réécrire, puisque rien n'a alors été modifié.
items[].tracking.openedboolean- Indique si une ouverture comptabilisée a été enregistrée, dérivé de `openCount > 0`.
items[].tracking.clickedboolean- Indique si un clic comptabilisé a été enregistré, dérivé de `clickCount > 0`.
items[].tracking.openCountnumber- Les ouvertures jugées causées par une personne, additionnées sur chaque copie du message. Les scanners et les proxys de confidentialité sont enregistrés mais exclus, et les rechargements répétés dans les trente secondes fusionnent en un seul.
items[].tracking.clickCountnumber- Les clics comptabilisés, additionnés sur les copies. Dédupliqués par lien et non par message, car suivre deux liens à quelques secondes d'intervalle représente deux actes, pas une répétition.
items[].tracking.firstOpenAtstring | null- La première ouverture comptabilisée parmi les copies, et null tant qu'il n'y en a aucune. Les hits machine ne la déplacent jamais.
items[].translationEmailTranslationResource- Jamais présent sur une ligne de liste : l'enregistrement de traduction vit dans la requête stockée, qu'une liste ne va délibérément pas chercher. Son absence ici ne dit rien sur le fait que le message ait été traduit ou non. Interrogez `get`.