Ruby

Lister et récupérer

`emails.list`, `emails.list_all`, `emails.iterate`, `emails.get` et `emails.list_events`.

emails.list

list_emails.rb

filters = {status: ["queued", "scheduled"], from: "[email protected]"} first = client.emails.list(**filters, limit: 50)second = client.emails.list(**filters, limit: 50, cursor: first.next_cursor) if first.next_cursor p first.items.size, second&.items&.size

Une page est une OpenEmail::Page avec items, has_more? et next_cursor. Renvoyez next_cursor comme cursor:, avec les mêmes filtres, pour obtenir la page suivante.

emails.iterate et emails.list_all

iterate_emails.rb

client.emails.iterate(status: "failed") do |email|  warn "#{email[:id]} #{email[:lastError]}"end failures = client.emails.list_all(status: "failed", from: "[email protected]")puts failures.size

Les deux suivent next_cursor pour vous. iterate ne récupère une page que lorsque le parcours l'atteint : break dans le bloc, ou first ou find sur l'Enumerator qu'il renvoie sans bloc, arrête donc les requêtes, tandis que list_all parcourt toutes les pages avant de renvoyer 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.list_events

get_email.rb

email = client.emails.get("msg_3f9a1c07d2b84e6a9c5b1f20")puts email[:status]p email[:recipients] events = client.emails.list_all_events("msg_3f9a1c07d2b84e6a9c5b1f20")events.each { |event| puts "#{event[:type]} #{event[:createdAt]}" }

get est le seul appel qui renvoie recipients, un Hash par adresse avec ses propres status, error et deliveredAt. Une liste de cinquante messages portant chacun ses destinataires, c'est une page de rapport que personne n'a demandée.

list_events lit la trace des événements d'un envoi, du plus ancien au plus récent : email.accepted, email.queued, email.sent, email.delivered, email.bounced, email.opened et les autres, chacun avec un Hash data dont la forme dépend de son type. list_all_events et iterate_events parcourent toute la trace pour vous. Les webhooks livrent un sous-ensemble de ces mêmes événements au fil de l'eau : c'est donc ici qu'il faut regarder quand un webhook a été manqué.

Paramètres

statusString or Array<String>: Un statut ou plusieurs (`queued`, `scheduled`, `sending`, `sent`, `partial`, `bounced`, `cancelled`, `failed`), correspondant à n'importe lequel de ceux donnés. `bounced` signifie que le message a rebondi pour chacun de ses destinataires, alors qu'un message qui a rebondi pour certains et atteint les autres affiche `partial`. La gem envoie un Array comme une seule valeur séparée par des virgules, car le serveur découpe sur les virgules, et une valeur hors de l'ensemble donne un 422 qui nomme la valeur inconnue.
broadcast_idString: Seulement les copies d'une diffusion, un id `brd_` issu de `broadcasts.send`. Chaque personne atteinte par une diffusion reçoit un message à elle, si bien que ceci liste à qui elle est partie et ce qu'il est advenu de chaque copie. `broadcasts.list_recipients` liste les mêmes personnes avec leurs ouvertures, clics et désabonnements.
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 la comparaison, et il s'agit d'une égalité, pas d'une correspondance de préfixe ou de domaine.
scheduled_fromTime, DateTime or String: Seulement les messages planifiés à cet instant ou plus tard. Avec `scheduled_to:` et `status: ["scheduled", "queued"]`, il liste ce qui attend de partir dans une fenêtre de temps, comme le fait le calendrier de l'application. Un message sans `scheduledAt` est exclu. Passez un Time, un DateTime ou un instant ISO 8601 avec son décalage : une Date Ruby est envoyée comme une date nue, que ces deux filtres refusent.
scheduled_toTime, DateTime or String: Seulement les messages planifiés à cet instant ou plus tôt. Un `scheduled_from:` postérieur à `scheduled_to:` donne un 422 `invalid_parameter`.
limitInteger: 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. Sur `list_all` et `iterate`, c'est la taille de chaque page qu'ils récupèrent.
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 cet espace de travail donne un 400 `invalid_cursor`.
api_keyString: Liste avec cette clé au lieu de celle du client.

Une clé restreinte à certaines adresses ne lit que les messages envoyés depuis les adresses qu'elle couvre, et la page est découpée après ce filtre : chaque page sauf la dernière contient donc toujours limit lignes. Un from: que la clé ne couvre pas renvoie une dernière page vide plutôt qu'un 403.

Réponse : OpenEmail::Page

itemsArray<Hash>: 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`.
has_more?Boolean: 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.
next_cursorString or nil: L'id à renvoyer comme `cursor:`, et nil sur la dernière page. `iterate` et `list_all` s'arrêtent quand il vaut nil ou que `has_more?` vaut false, car une page qui annonce d'autres résultats sans nommer de curseur tournerait en boucle sans fin.

Chaque élément

objectString: Toujours `email` sur une ligne de cette liste.
idString: L'id propre à cette API, `msg_…`. C'est ce que prend tout autre appel emails, et ce qu'un curseur désigne.
statusString: 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. `bounced` signifie qu'il a rebondi chez chaque destinataire après son départ, donc personne ne l'a, et chaque destinataire dans `get` en donne la raison.
modeString: `live` ou `test`, repris de la clé qui l'a envoyé. Un envoi de test est enregistré ici et jamais transmis.
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 Hash, 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 qu'elle couvre.
subjectString or nil: L'objet tel que stocké. nil sur un message enregistré sans objet.
messageIdString or nil: Le Message-ID RFC 5322, pas notre id. nil 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 `id`.
threadIdString or nil: Le thread auquel ce message appartient, quand un thread a été donné ou attribué. nil sinon.
transportString or nil: Par où les octets sont partis. nil jusqu'à l'expédition. Des enregistrements stockés peuvent encore nommer des transports qui ne sont plus utilisés : traitez donc une valeur que vous ne connaissez pas comme une information plutôt que comme une erreur.
attemptsInteger: Combien de tentatives d'expédition le message a connues, 0 avant la première.
lastErrorString or nil: La dernière erreur d'expédition, rédigée pour un humain. nil tant que rien n'a échoué.
scheduledAtString or nil: Quand le message doit partir, sous forme d'instant ISO 8601. nil 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`.
cancellableUntilString or nil: L'instant où le message doit partir, portant la même valeur que `scheduledAt` sur tout envoi différé et nil sur un envoi qui ne l'était pas. C'est un horodatage à 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`.
sentAtString or nil: Quand il est parti. nil 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.
tagsHash: Les libellés fournis à l'envoi, renvoyés tels quels et jamais interprétés. Toujours un Hash, vide quand aucun n'a été défini et jamais nil, et seulement renvoyés : cette liste filtre sur `status`, `from`, `broadcast_id` et la fenêtre de planification, donc un tag se lit sur un message mais ne sert pas à le trouver.
broadcastIdString or nil: La diffusion `brd_` dont ce message est une copie, ou nil pour un message envoyé seul.
sourceString: Quelle surface a demandé l'envoi : `composer`, `api`, `mcp`, `ai` ou `queue`. `api`, c'est ce client.
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é.
trackingHash: 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ù un `openCount` de 0 se lirait comme « personne ne l'a ouvert ».
translationHash: 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`.

Le suivi d'un élément

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.
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é.
openedBoolean: Indique si une ouverture comptabilisée a été enregistrée, dérivé d'un `openCount` supérieur à 0.
clickedBoolean: Indique si un clic comptabilisé a été enregistré, dérivé d'un `clickCount` supérieur à 0.
openCountInteger: 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.
clickCountInteger: 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.
firstOpenAtString or nil: La première ouverture comptabilisée parmi les copies, et nil tant qu'il n'y en a aucune. Les accès automatisés ne la déplacent jamais.