Paginación

Cada lista paginada tiene tres métodos. list obtiene una página y devuelve una OpenEmail::Page. list_all sigue el cursor por todas las páginas y devuelve un solo Array. iterate recorre las mismas páginas elemento a elemento: pasa cada elemento a un bloque, o devuelve un Enumerator cuando no le das ninguno. Los tres aceptan los filtros de la lista, limit:, cursor: y 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?

Los mismos tres nombres se repiten allí donde un espacio de nombres tiene más de una lista, nombrados según la lista que recorren: list_events, list_all_events e iterate_events en emails, list_deliveries, list_all_deliveries e iterate_deliveries en webhooks, y así sucesivamente.

Una página es un objeto Data de Ruby, así que está congelada, se compara por valor y se convierte en un Hash con to_h.

Con un bloque, iterate recorre todas las páginas en ese momento y le pasa cada elemento. Sin él, devuelve un Enumerator y no obtiene nada hasta que lo consumes. En ambos casos solo pide la página siguiente una vez entregados todos los elementos de la actual, así que todo lo que se detiene antes de tiempo detiene también las solicitudes: first(10) solo lee las páginas que necesitan diez elementos, find se detiene en la coincidencia y break en un bloque termina el recorrido.

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] }

Un método de Enumerable que necesita todos los elementos, como select, map o count llamado directamente sobre el Enumerator, lee todas las páginas antes de devolver, igual que list_all. Antepón lazy para encadenarlos y poder detenerte antes de tiempo.

Un cursor es opaco. Guarda el next_cursor de la última página que leíste y devuélvelo como cursor: para continuar desde ahí, en una solicitud posterior o en otro proceso. list_all e iterate también aceptan cursor: y empiezan su recorrido después de él.

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: es el tamaño de cada página, no un total. En list es cuántas filas vuelven. En list_all e iterate es cuántas pide cada solicitud, así que un valor mayor significa menos idas y vueltas para las mismas filas. Cada lista tiene su propio rango y valor por defecto, casi siempre de 1 a 100 con 25 si no envías ninguno, y un valor fuera del rango se rechaza en lugar de ajustarse. La página de cada lista indica su rango.

• —Cuando una página dice que has_more? es false.
• —Cuando una página no lleva next_cursor, ya que una página que afirma que hay más sin nombrar ningún cursor daría vueltas para siempre.
• —Cuando la API devuelve el mismo cursor que acaba de recibir, por el mismo motivo.

Cada página es un GET, así que se reintenta por sí sola como cualquier lectura antes de que se lance nada. Un fallo que sobrevive a los reintentos se lanza desde list_all, y los elementos ya obtenidos se descartan. En iterate, los elementos de las páginas anteriores ya se han entregado para entonces, así que haz que lo que hace el bloque pueda ejecutarse dos veces sin riesgo, o pagina con list y guarda cada next_cursor para que un segundo intento pueda empezar donde se detuvo el primero.

threads.list y drafts.list, con sus list_all e iterate, paginan con pageToken y nextPageToken de la API en lugar de con un cursor. La gema oculta la diferencia: pasa el token como cursor: y léelo de 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

Unas pocas listas responden con algo más que filas, y devuelven su propio objeto Data en lugar de OpenEmail::Page.

Algunas listas paginan por desplazamiento, por número de página o por un cursor numérico propio, y devuelven el cuerpo analizado tal como llegó, un Hash con data, en lugar de una OpenEmail::Page. No tienen list_all ni iterate, así que las paginas tú mismo.

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