Pagination

Chaque liste paginée a trois méthodes. list récupère une page et renvoie une OpenEmail::Page. list_all suit le curseur à travers toutes les pages et renvoie un seul Array. iterate parcourt les mêmes pages un élément à la fois : il passe chaque élément à un bloc, ou renvoie un Enumerator si vous ne lui en donnez pas. Les trois prennent les filtres de la liste, limit:, cursor: et api_key:.

page = client.emails.list(status: "failed", limit: 50)page.items.each { |email| puts "#{email[:id]} #{email[:lastError]}" } failures = client.emails.list_all(status: "failed") client.emails.iterate(status: "failed") do |email|  puts email[:id]end puts failures.size, page.has_more?

Les trois mêmes noms reviennent partout où un espace de noms a plus d'une liste, nommés d'après la liste qu'ils parcourent : list_events, list_all_events et iterate_events sur emails, list_deliveries, list_all_deliveries et iterate_deliveries sur webhooks, et ainsi de suite.

Une page est un objet Data de Ruby : elle est donc gelée, se compare par valeur et se convertit en Hash avec to_h.

Avec un bloc, iterate parcourt immédiatement toutes les pages et lui passe chaque élément. Sans bloc, il renvoie un Enumerator et ne récupère rien tant que vous ne le consommez pas. Dans les deux cas, il ne demande la page suivante qu'une fois chaque élément de la page courante passé : tout ce qui s'arrête tôt arrête donc aussi les requêtes. first(10) ne lit que le nombre de pages nécessaire à dix éléments, find s'arrête à la correspondance, et break dans un bloc met fin au parcours.

latest = client.emails.iterate(status: "failed", limit: 100).first(10) invoice = client.emails.iterate(status: "failed").find do |email|  email.dig(:tags, :invoice) == "inv_2026_09_4192"end from_api = client.emails.iterate(status: "bounced").lazy.select { |email| email[:source] == "api" }.first(5) p latest.size, invoice&.fetch(:id), from_api.map { |email| email[:id] }

Une méthode d'Enumerable qui a besoin de tous les éléments, comme select, map ou count appelée directement sur l'Enumerator, lit toutes les pages avant de retourner, comme le fait list_all. Placez lazy devant pour les enchaîner tout en pouvant vous arrêter tôt.

Un curseur est opaque. Gardez le next_cursor de la dernière page lue et renvoyez-le comme cursor: pour reprendre à partir de là, dans une requête ultérieure ou dans un autre processus. list_all et iterate prennent aussi cursor: et commencent leur parcours après lui.

first_page = client.emails.list(status: "failed", limit: 25)saved = first_page.next_cursor if saved  rest = client.emails.list_all(status: "failed", cursor: saved)  puts rest.sizeend

limit: est la taille de chaque page, pas un total. Sur list, c'est le nombre de lignes renvoyées. Sur list_all et iterate, c'est le nombre que demande chaque requête : une valeur plus grande signifie donc moins d'allers-retours pour les mêmes lignes. Chaque liste a sa propre plage et sa propre valeur par défaut, le plus souvent de 1 à 100 avec 25 si vous n'envoyez rien, et une valeur hors de la plage est refusée plutôt que ramenée dans les bornes. La page de chaque liste indique sa plage.

• —Quand une page indique que has_more? vaut false.
• —Quand une page ne porte pas de next_cursor, car une page qui annonce une suite sans nommer de curseur bouclerait à l'infini.
• —Quand l'API renvoie le curseur qu'elle vient de recevoir, pour la même raison.

Chaque page est un GET : elle est donc réessayée isolément, comme toute lecture, avant que quoi que ce soit ne lève une erreur. Un échec qui survit aux réessais remonte de list_all sous forme d'erreur, et les éléments déjà récupérés sont abandonnés. Dans iterate, les éléments des pages précédentes ont déjà été passés à ce stade : faites donc en sorte que le bloc puisse s'exécuter deux fois sans risque, ou paginez avec list et gardez chaque next_cursor pour qu'une deuxième tentative puisse reprendre là où la première s'est arrêtée.

threads.list et drafts.list, avec leurs list_all et iterate, paginent avec le pageToken et le nextPageToken de l'API plutôt qu'avec un curseur. La gem masque la différence : passez le jeton comme cursor: et lisez-le dans next_cursor.

page = client.threads.list(folder: "inbox", limit: 50)later = client.threads.list(folder: "inbox", limit: 50, cursor: page.next_cursor) if page.has_more? p page.items.size, later&.items&.size

Quelques listes répondent avec plus que des lignes, et renvoient leur propre objet Data à la place d'OpenEmail::Page.

Certaines listes paginent par offset, par numéro de page ou par un curseur numérique qui leur est propre, et renvoient le corps analysé tel quel, un Hash avec data, plutôt qu'une OpenEmail::Page. Elles n'ont ni list_all ni iterate : vous les paginez vous-même.

offset = 0 loop do  batch = client.subscriptions.list(status: "active", limit: 50, offset:)  batch[:data].each { |row| puts "#{row[:senderEmail]} #{row[:total]}" }   break unless batch[:hasMore]   offset += batch[:data].sizeend