Пагинация

У каждого списка с постраничной выдачей есть три метода. list получает одну страницу и возвращает OpenEmail\Result\Page. listAll следует за курсором через все страницы и возвращает один массив. iterate обходит те же страницы по одному элементу и возвращает Generator, который запрашивает следующую страницу, только когда вы до неё дойдёте. Все три принимают фильтры списка, limit:, cursor: и apiKey:.

$page = $client->emails->list(status: 'failed', limit: 50); foreach ($page as $email) {    echo $email['id'], ' ', $email['lastError'] ?? '', PHP_EOL;} $failures = $client->emails->listAll(status: 'failed'); foreach ($client->emails->iterate(status: 'failed') as $email) {    echo $email['id'], PHP_EOL;} echo count($failures), ' ', $page->hasMore ? 'more to come' : 'that is all', PHP_EOL;

Те же три имени повторяются везде, где у пространства имён больше одного списка, и называются по списку, который обходят: listEvents, listAllEvents и iterateEvents в emails, listDeliveries, listAllDeliveries и iterateDeliveries в webhooks и так далее.

Страница неизменяема: её свойства объявлены как readonly. Она также реализует IteratorAggregate и Countable, поэтому foreach ($page as $item) обходит её строки, а count($page) их считает.

iterate ничего не запрашивает, пока вы не начнёте его обходить, и запрашивает следующую страницу, только когда все элементы текущей уже выданы, поэтому всё, что останавливается раньше, останавливает и запросы: break завершает обход, как и возврат из функции, в которой находится цикл.

$latest = []; foreach ($client->emails->iterate(status: 'failed', limit: 100) as $email) {    $latest[] = $email;     if (count($latest) === 10) {        break;    }} $invoice = null; foreach ($client->emails->iterate(status: 'failed') as $email) {    if (($email['tags']['invoice'] ?? null) === 'inv_2026_09_4192') {        $invoice = $email;         break;    }} echo count($latest), ' ', $invoice['id'] ?? 'not found', PHP_EOL;

Всё, чему нужны все элементы, например iterator_to_array(), вызванный на Generator, читает все страницы, прежде чем вернуть результат, как это делает listAll.

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

$firstPage = $client->emails->list(status: 'failed', limit: 25);$saved = $firstPage->nextCursor; if ($saved !== null) {    $rest = $client->emails->listAll(status: 'failed', cursor: $saved);    echo count($rest), PHP_EOL;}

limit: является размером каждой страницы, а не общим количеством. В list это число возвращаемых строк. В listAll и iterate это число строк, которое запрашивает каждый запрос, поэтому большее значение означает меньше обращений к серверу за те же строки. У каждого списка свой диапазон и значение по умолчанию, чаще всего от 1 до 100 и 25, если ничего не передано, а значение вне диапазона отклоняется, а не подрезается. Диапазон указан в справочнике по каждому списку.

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

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

threads->list и drafts->list вместе со своими listAll и iterate листают с помощью pageToken и nextPageToken из API, а не курсора. Клиент скрывает эту разницу: передавайте токен как cursor: и читайте его из nextCursor.

$page = $client->threads->list(folder: 'inbox', limit: 50);$later = $page->hasMore ? $client->threads->list(folder: 'inbox', limit: 50, cursor: $page->nextCursor) : null; echo count($page), ' ', $later === null ? 0 : count($later), PHP_EOL;

Несколько списков отвечают не только строками и возвращают собственный объект из OpenEmail\Result вместо Page. Каждый из них неизменяем, реализует IteratorAggregate по своим строкам и Countable.

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

$offset = 0; do {    $batch = $client->subscriptions->list(status: 'active', limit: 50, offset: $offset);     foreach ($batch['data'] as $row) {        echo $row['senderEmail'], ' ', $row['total'], PHP_EOL;    }     $offset += count($batch['data']);} while ($batch['hasMore'] && $batch['data'] !== []);