Paginierung
`list` für eine Seite, `list_all` für alle Seiten und `iterate` für einen Eintrag nach dem anderen.
Eine Seite: 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']Eine Seite ist {'items': [...], 'hasMore': ..., 'nextCursor': ...}. Übergeben Sie nextCursor mit denselben Filtern wieder als cursor=, um die nächste Seite zu erhalten.
nextCursor ist auf der letzten Seite None, und hasMore sagt, ob über diese hinaus weitere Zeilen passen. In openemail.types ist eine Seite ein Page[T], emails.list gibt also eine Page[EmailResource] zurück, und ein Typprüfer weiß, was jeder Eintrag enthält.
Die API paginiert Threads und Entwürfe mit einem pageToken. Der Client gibt es Ihnen als nextCursor heraus und nimmt es als cursor= zurück, wie bei jeder anderen Liste, und list_all und iterate folgen ihm für Sie. Es ist opak: Geben Sie zurück, was Sie bekommen haben, und bauen Sie nie selbst eines.
Alle Seiten: 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 folgt nextCursor bis zur letzten Seite und gibt eine einzige list zurück. Jede Seite wird abgerufen, bevor es zurückkehrt, geben Sie ihm daher einen Filter, der endet.
addresses.list_all ist die Ausnahme, die etwas anderes zurückgibt: das ganze Adressbuch, {'unrestricted': ..., 'addresses': [...], 'domains': [...]}, mit den Adressen aller Seiten darin.
Einer nach dem anderen: 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 gibt einen Generator zurück. Der Aufruf selbst sendet nichts: Die erste Seite wird abgerufen, wenn die Schleife nach ihrem ersten Eintrag fragt, und jede weitere erst, wenn die Schleife das Ende der vorherigen erreicht. Das Verlassen der Schleife oder ein Ausschnitt mit itertools.islice stoppt die Anfragen.
limit= bei list_all und iterate ist die Größe jeder abgerufenen Seite, keine Obergrenze dafür, wie viele Einträge Sie bekommen, ein größeres limit bedeutet also weniger Anfragen. cursor= beginnt den Durchlauf bei einer Seite, die Sie bereits haben. Beide stoppen, wenn hasMore false ist oder nextCursor None, und auch dann, wenn eine Seite den Cursor nennt, mit dem sie abgerufen wurde, sodass eine fehlerhafte Seite keine Endlosschleife erzeugen kann.
Listen innerhalb eines Namespace
list_all und iterate blättern durch denselben Endpunkt wie das list daneben, und das gilt auch für die anderen Paare, die nach der Liste benannt sind, die sie durchlaufen. Jedes Paar nimmt dieselben Filter wie seine Liste.
| Namespace | Eine Seite | Alle Seiten | Einer nach dem anderen |
|---|---|---|---|
| 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 |
Seiten mit zusätzlichen Feldern
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']))Einige Listen liefern mehr als eine bloße Seite. contacts.list_people ergänzt seen neben items, hasMore und nextCursor, temp_mail.list_messages ergänzt expiresAt, und addresses.list gibt addresses anstelle von items zurück, neben unrestricted, domains, hasMore und nextCursor. Jede wird dennoch mit cursor= fortgesetzt und mit ihrem list_all und iterate durchlaufen.
Zwei Listen paginieren anders. templates.list_sends zählt Seiten: Übergeben Sie page= und page_size=, und lesen Sie total, page und pageSize neben items. imports.list_failures bleibt so, wie die API es sendet, {'object': 'list', 'data': [...], 'nextCursor': ...}, und wird mit after= fortgesetzt, der Zahl in nextCursor. Keine von beiden hat ein list_all oder ein iterate.
Seitengrößen
Die meisten Listen nehmen ein limit= von 1 bis 100 mit dem Standardwert 25, die beiden Zahlen in PAGE_LIMITS (PAGE_LIMITS.MAX_LIMIT und PAGE_LIMITS.DEFAULT_LIMIT). contacts.list, audiences.list_contacts, broadcasts.list_recipients und die tracking-Listen nehmen bis zu 200 mit einem Standardwert von 50, und temp_mail.list_messages nimmt bis zu 50. Ein Wert außerhalb des Bereichs wird mit einem 422 abgelehnt, statt begrenzt zu werden.
Auf AsyncOpenEmail
Der asynchrone Client paginiert genauso. Auf list und list_all wird mit await gewartet, und iterate gibt einen asynchronen Iterator zurück, den Sie mit async for durchlaufen, ohne await vor dem Aufruf.
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())