Paginação
`list` para uma página, `list_all` para todas as páginas e `iterate` para um item de cada vez.
Uma página: list
cursor: str | None = None while True: page = client.emails.list(status='failed', limit=50, cursor=cursor) for email in page['items']: print(email['id'], email['lastError']) if not page['hasMore'] or page['nextCursor'] is None: break cursor = page['nextCursor']Uma página é {'items': [...], 'hasMore': ..., 'nextCursor': ...}. Passe nextCursor de volta como cursor=, com os mesmos filtros, para obter a página seguinte.
nextCursor é None na última página, e hasMore diz se há mais linhas que correspondem além desta. Em openemail.types uma página é Page[T], por isso emails.list devolve um Page[EmailResource] e um verificador de tipos sabe o que cada item contém.
A API pagina as conversas e os rascunhos com um pageToken. O cliente entrega-lho como nextCursor e recebe-o de volta como cursor=, tal como em todas as outras listagens, e list_all e iterate seguem-no por si. É opaco: devolva o que lhe foi dado e nunca construa um.
Todas as páginas: list_all
complaints = client.suppressions.list_all(reason='complaint')print(len(complaints), [row['email'] for row in complaints]) book = client.addresses.list_all()print(book['unrestricted'], len(book['addresses']), len(book['domains']))list_all segue nextCursor até à última página e devolve uma única list. Todas as páginas são obtidas antes de devolver o resultado, por isso dê-lhe um filtro que termine.
addresses.list_all é o único que devolve outra coisa: o livro de endereços completo, {'unrestricted': ..., 'addresses': [...], 'domains': [...]}, com os endereços de todas as páginas lá dentro.
Um de cada vez: iterate
from itertools import islice for email in client.emails.iterate(status='bounced'): if email['createdAt'] < '2026-09-01': break print(email['id'], email['lastError']) first_ten = list(islice(client.threads.iterate(folder='inbox'), 10))print([thread['id'] for thread in first_ten])iterate devolve um gerador. Chamá-lo não envia nada: a primeira página é obtida quando o ciclo pede o primeiro item, e cada página seguinte só quando o ciclo chega ao fim da anterior. Sair do ciclo, ou tirar uma fatia com itertools.islice, interrompe os pedidos.
limit= em list_all e iterate é o tamanho de cada página que obtêm, não um limite de quantos itens recebe, por isso um limit maior significa menos pedidos. cursor= começa o percurso a partir de uma página que já tem. Ambos param quando hasMore é falso ou nextCursor é None, e também quando uma página indica o cursor que a obteve, por isso uma página com mau comportamento não pode provocar um ciclo infinito.
Listas dentro de um espaço de nomes
list_all e iterate paginam o mesmo endpoint que o list ao lado deles, e o mesmo fazem os outros pares com o nome da lista que percorrem. Cada par aceita os mesmos filtros que a sua lista.
| Espaço de nomes | Uma página | Todas as páginas | Um de cada vez |
|---|---|---|---|
| emails | list_events | list_all_events | iterate_events |
| calendar | list_events | list_all_events | iterate_events |
| templates | list_versions | list_all_versions | iterate_versions |
| templates | list_images | list_all_images | iterate_images |
| tracking | list_opens | list_all_opens | iterate_opens |
| tracking | list_clicks | list_all_clicks | iterate_clicks |
| rules | list_runs | list_all_runs | iterate_runs |
| audiences | list_contacts | list_all_contacts | iterate_contacts |
| broadcasts | list_recipients | list_all_recipients | iterate_recipients |
| contacts | list_people | list_all_people | iterate_people |
| contacts | list_threads | list_all_threads | iterate_threads |
| domains | list_addresses | list_all_addresses | iterate_addresses |
| forms | list_submissions | list_all_submissions | iterate_submissions |
| members | list_invitations | list_all_invitations | iterate_invitations |
| files | list_links | list_all_links | iterate_links |
| temp_mail | list_messages | list_all_messages | iterate_messages |
| webhooks | list_deliveries | list_all_deliveries | iterate_deliveries |
| webhooks | list_workspace_deliveries | list_all_workspace_deliveries | iterate_workspace_deliveries |
| webhooks | list_activity | list_all_activity | iterate_activity |
| webhooks | list_workspace_activity | list_all_workspace_activity | iterate_workspace_activity |
| keys | list_requests | list_all_requests | iterate_requests |
| keys | list_activity | list_all_activity | iterate_activity |
| keys | list_workspace_requests | list_all_workspace_requests | iterate_workspace_requests |
| keys | list_workspace_activity | list_all_workspace_activity | iterate_workspace_activity |
Páginas que trazem mais
people = client.contacts.list_people(sort='recent', limit=50)print(len(people['items']), people['seen'], people['nextCursor']) sends = client.templates.list_sends('order-shipped', page=2, page_size=50)print(sends['total'], sends['page'], sends['pageSize'], len(sends['items']))Algumas listas trazem mais do que uma página. contacts.list_people acrescenta seen ao lado de items, hasMore e nextCursor, temp_mail.list_messages acrescenta expiresAt, e addresses.list devolve addresses em vez de items, ao lado de unrestricted, domains, hasMore e nextCursor. Ainda assim, cada uma continua com cursor= e percorre-se com o seu list_all e o seu iterate.
Duas listas paginam de outra forma. templates.list_sends conta páginas: passe page= e page_size=, e leia total, page e pageSize ao lado de items. imports.list_failures fica tal como a API a envia, {'object': 'list', 'data': [...], 'nextCursor': ...}, e continua com after=, o número que está em nextCursor. Nenhuma das duas tem list_all nem iterate.
Tamanhos de página
A maioria das listas aceita um limit= de 1 a 100, com 25 por omissão, os dois números de PAGE_LIMITS (PAGE_LIMITS.MAX_LIMIT e PAGE_LIMITS.DEFAULT_LIMIT). contacts.list, audiences.list_contacts, broadcasts.list_recipients e as listas de tracking aceitam até 200 com 50 por omissão, e temp_mail.list_messages aceita até 50. Um valor fora do intervalo é recusado com 422 em vez de ser ajustado ao limite.
Em AsyncOpenEmail
O cliente assíncrono pagina da mesma forma. list e list_all são chamados com await, e iterate devolve um iterador assíncrono que percorre com async for, sem await antes da chamada.
import asyncio from openemail import AsyncOpenEmail async def main() -> None: async with AsyncOpenEmail() as client: page = await client.emails.list(status='failed', limit=50) print(len(page['items']), page['nextCursor']) everyone = await client.members.list_all() print(len(everyone)) async for delivery in client.webhooks.iterate_deliveries('whe_…', status='failed'): print(delivery['eventType'], delivery['responseCode']) asyncio.run(main())