Paginação

Todas as listas paginadas têm três métodos. list obtém uma página e devolve uma OpenEmail::Page. list_all segue o cursor por todas as páginas e devolve um único Array. iterate percorre as mesmas páginas um item de cada vez: passa cada item a um bloco, ou devolve um Enumerator quando não lhe dá nenhum. Os três aceitam os filtros da lista, limit:, cursor: e 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?

Os mesmos três nomes repetem-se sempre que um espaço de nomes tem mais do que uma lista, com o nome da lista que percorrem: list_events, list_all_events e iterate_events em emails, list_deliveries, list_all_deliveries e iterate_deliveries em webhooks, e assim por diante.

Uma página é um objeto Data do Ruby, por isso está congelada, compara-se por valor e converte-se num Hash com to_h.

Com um bloco, iterate percorre todas as páginas nesse momento e passa-lhe cada item. Sem bloco, devolve um Enumerator e não obtém nada até o consumir. Em ambos os casos só pede a página seguinte depois de entregues todos os itens da atual, por isso tudo o que para mais cedo também para os pedidos: first(10) só lê as páginas de que dez itens precisam, find para na correspondência e break num bloco termina o percurso.

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

Um método de Enumerable que precisa de todos os itens, como select, map ou count chamado diretamente sobre o Enumerator, lê todas as páginas antes de devolver, tal como list_all. Ponha lazy à frente para os encadear e continuar a poder parar mais cedo.

Um cursor é opaco. Guarde o next_cursor da última página que leu e devolva-o como cursor: para continuar a partir daí, num pedido posterior ou noutro processo. list_all e iterate também aceitam cursor: e começam o seu percurso a seguir a ele.

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: é o tamanho de cada página, não um total. Em list é quantas linhas voltam. Em list_all e iterate é quantas cada pedido pede, por isso um valor maior significa menos idas e voltas para as mesmas linhas. Cada lista tem o seu próprio intervalo e valor predefinido, quase sempre de 1 a 100 com 25 se não enviar nenhum, e um valor fora do intervalo é recusado em vez de ajustado. A página de cada lista indica o seu intervalo.

• —Quando uma página diz que has_more? é false.
• —Quando uma página não traz next_cursor, já que uma página que diz haver mais sem indicar nenhum cursor ficaria em ciclo para sempre.
• —Quando a API devolve o mesmo cursor que acabou de receber, pelo mesmo motivo.

Cada página é um GET, por isso é repetida por si só, como qualquer leitura, antes de se lançar o que quer que seja. Uma falha que sobreviva às repetições é lançada a partir de list_all, e os itens já obtidos são descartados. Em iterate, os itens das páginas anteriores já foram entregues nessa altura, por isso torne seguro executar duas vezes o que o bloco faz, ou pagine com list e guarde cada next_cursor para que uma segunda tentativa possa começar onde a primeira parou.

threads.list e drafts.list, com os seus list_all e iterate, paginam com o pageToken e o nextPageToken da API em vez de um cursor. A gem esconde a diferença: passe o token como cursor: e leia-o 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

Algumas listas respondem com mais do que linhas, e devolvem um objeto Data próprio em vez de OpenEmail::Page.

Algumas listas paginam por deslocamento, por número de página ou por um cursor numérico próprio, e devolvem o corpo analisado tal como chegou, um Hash com data, em vez de uma OpenEmail::Page. Não têm list_all nem iterate, por isso tem de as paginar você mesmo.

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