Paginação

Todas as listas paginadas têm três métodos. list obtém uma página e devolve uma OpenEmail\Result\Page. listAll segue o cursor por todas as páginas e devolve um único array. iterate percorre as mesmas páginas um item de cada vez e devolve um Generator, que só obtém a página seguinte quando lá chega. Os três aceitam os filtros da lista, limit:, cursor: e 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;

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: listEvents, listAllEvents e iterateEvents em emails, listDeliveries, listAllDeliveries e iterateDeliveries em webhooks, e assim por diante.

Uma página é imutável: as suas propriedades são readonly. É também IteratorAggregate e Countable, por isso foreach ($page as $item) percorre as suas linhas e count($page) conta-as.

iterate não pede nada até começar a percorrê-lo, e 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: break termina o percurso, tal como sair da função que contém o ciclo.

$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;

Tudo o que precise de todos os itens, como iterator_to_array() chamado sobre o Generator, lê todas as páginas antes de devolver, tal como listAll.

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

$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: é o tamanho de cada página, não um total. Em list é quantas linhas voltam. Em listAll 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 referência de cada lista indica o seu intervalo.

• —Quando uma página diz que hasMore é false.
• —Quando uma página não traz nextCursor, já que uma página que diz haver mais sem indicar nenhum cursor ficaria em ciclo para sempre.
• —Quando a API devolve um cursor que o percurso já seguiu, 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 listAll, 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 ciclo faz, ou pagine com list e guarde cada nextCursor para que uma segunda tentativa possa começar onde a primeira parou.

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

Algumas listas respondem com mais do que linhas, e devolvem um objeto próprio de OpenEmail\Result em vez de Page. Cada um é imutável, IteratorAggregate sobre as suas linhas e Countable.

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

$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'] !== []);