Paginación

Cada lista paginada tiene tres métodos. list obtiene una página y devuelve una OpenEmail\Result\Page. listAll sigue el cursor por todas las páginas y devuelve un solo array. iterate recorre las mismas páginas elemento a elemento y devuelve un Generator, que solo obtiene la página siguiente cuando llegas a ella. Los tres aceptan los filtros de la lista, limit:, cursor: y 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;

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: listEvents, listAllEvents e iterateEvents en emails, listDeliveries, listAllDeliveries e iterateDeliveries en webhooks, y así sucesivamente.

Una página es inmutable: sus propiedades son readonly. También es IteratorAggregate y Countable, así que foreach ($page as $item) recorre sus filas y count($page) las cuenta.

iterate no pide nada hasta que empiezas a recorrerlo, y 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: break termina el recorrido, y también salir de la función que contiene el bucle.

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

Todo lo que necesita todos los elementos, como iterator_to_array() llamado sobre el Generator, lee todas las páginas antes de devolver, igual que listAll.

Un cursor es opaco. Guarda el nextCursor 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. listAll e iterate también aceptan cursor: y empiezan su recorrido después de él.

$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: es el tamaño de cada página, no un total. En list es cuántas filas vuelven. En listAll 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 referencia de cada lista indica su rango.

• —Cuando una página dice que hasMore es false.
• —Cuando una página no lleva nextCursor, 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 un cursor que el recorrido ya siguió, 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 listAll, y los elementos ya obtenidos se descartan. Con iterate, los elementos de las páginas anteriores ya se han entregado para entonces, así que haz que lo que hace el bucle pueda ejecutarse dos veces sin riesgo, o pagina con list y guarda cada nextCursor para que un segundo intento pueda empezar donde se detuvo el primero.

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

Unas pocas listas responden con algo más que filas, y devuelven su propio objeto de OpenEmail\Result en lugar de Page. Cada uno es inmutable, IteratorAggregate sobre sus filas y Countable.

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

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