Пагинация

У каждого списка с постраничной выдачей есть три метода. list получает одну страницу и возвращает OpenEmail::Page. list_all следует за курсором через все страницы и возвращает один Array. iterate обходит те же страницы по одному элементу: передаёт каждый элемент в блок или возвращает Enumerator, если блок не передан. Все три принимают фильтры списка, limit:, cursor: и 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?

Те же три имени повторяются везде, где у пространства имён больше одного списка, и называются по списку, который обходят: list_events, list_all_events и iterate_events в emails, list_deliveries, list_all_deliveries и iterate_deliveries в webhooks и так далее.

Страница является объектом Ruby Data, поэтому она заморожена, сравнивается по значению и превращается в Hash через to_h.

С блоком iterate сразу обходит все страницы и передаёт в блок каждый элемент. Без блока он возвращает Enumerator и ничего не запрашивает, пока вы его не потребите. В обоих случаях он запрашивает следующую страницу, только когда все элементы текущей уже переданы, поэтому всё, что останавливается раньше, останавливает и запросы: first(10) читает столько страниц, сколько нужно для десяти элементов, find останавливается на совпадении, а break в блоке завершает обход.

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

Метод Enumerable, которому нужны все элементы, например select, map или count, вызванный прямо на Enumerator, читает все страницы, прежде чем вернуть результат, как это делает list_all. Поставьте перед ними lazy, чтобы выстроить цепочку и всё равно остановиться раньше.

Курсор непрозрачен. Сохраните next_cursor последней прочитанной страницы и передайте его обратно как cursor:, чтобы продолжить с этого места в более позднем запросе или в другом процессе. list_all и iterate тоже принимают cursor: и начинают обход после него.

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: является размером каждой страницы, а не общим количеством. В list это число возвращаемых строк. В list_all и iterate это число строк, которое запрашивает каждый запрос, поэтому большее значение означает меньше обращений к серверу за те же строки. У каждого списка свой диапазон и значение по умолчанию, чаще всего от 1 до 100 и 25, если ничего не передано, а значение вне диапазона отклоняется, а не подрезается. Диапазон указан на странице каждого списка.

• —Когда страница сообщает, что has_more? равно false.
• —Когда страница не несёт next_cursor, поскольку страница, которая заявляет о продолжении, но не называет курсора, зациклилась бы навсегда.
• —Когда API возвращает тот же курсор, который ему только что передали, по той же причине.

Каждая страница является GET, поэтому, как любое чтение, она сама повторяется, прежде чем что-либо выбросит исключение. Сбой, переживший повторы, выбрасывается из list_all, а уже полученные элементы отбрасываются. В iterate элементы предыдущих страниц к этому моменту уже переданы в блок, поэтому сделайте действия блока безопасными для повторного выполнения или листайте через list и сохраняйте каждый next_cursor, чтобы вторая попытка могла начать с того места, где остановилась первая.

threads.list и drafts.list вместе со своими list_all и iterate листают с помощью pageToken и nextPageToken из API, а не курсора. Гем скрывает эту разницу: передавайте токен как cursor: и читайте его из 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

Несколько списков отвечают не только строками и возвращают собственный объект Data вместо OpenEmail::Page.

Некоторые списки листают по смещению, по номеру страницы или по собственному числовому курсору и возвращают разобранное тело как есть, Hash с data, а не OpenEmail::Page. У них нет list_all или iterate, поэтому листать их приходится самостоятельно.

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