Faqosja
`list` për një faqe, `list_all` për të gjitha faqet, dhe `iterate` për një element në një kohë.
Një faqe: 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']Një faqe është {'items': [...], 'hasMore': ..., 'nextCursor': ...}. Jepeni nextCursor prapa si cursor=, me të njëjtët filtra, për faqen pas saj.
nextCursor është None në faqen e fundit, dhe hasMore tregon nëse ka më shumë rreshta që përputhen përtej kësaj. Në openemail.types një faqe është Page[T], kështu që emails.list kthen një Page[EmailResource] dhe një kontrollues tipash e di se çfarë mban çdo element.
API-ja i faqos bisedat dhe draftet me një pageToken. Klienti jua jep si nextCursor dhe e merr prapë si cursor=, si te çdo listë tjetër, dhe list_all e iterate e ndjekin për ju. Është opak: ktheni atë që ju është dhënë dhe mos e ndërtoni kurrë vetë.
Të gjitha faqet: 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 e ndjek nextCursor deri në faqen e fundit dhe kthen një list të vetme. Çdo faqe merret para se ajo të kthehet, ndaj jepini një filtër që ka fund.
addresses.list_all është ajo që kthen diçka tjetër: gjithë librin e adresave, {'unrestricted': ..., 'addresses': [...], 'domains': [...]}, me adresat e të gjitha faqeve brenda.
Një nga një: 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 kthen një gjenerator. Thirrja e saj nuk dërgon asgjë: faqja e parë merret kur cikli kërkon elementin e saj të parë, dhe çdo faqe pas saj vetëm kur cikli arrin në fund të asaj të mëparshme. Dalja nga cikli, ose marrja e një pjese me itertools.islice, i ndal kërkesat.
limit= te list_all dhe iterate është madhësia e çdo faqeje që marrin, jo një tavan për sa elemente merrni, kështu që një limit më i madh do të thotë më pak kërkesa. cursor= e nis përshkimin nga një faqe që e keni tashmë. Të dyja ndalen kur hasMore është false ose nextCursor është None, dhe gjithashtu kur një faqe emërton kursorin që e solli, kështu që një faqe e prishur nuk mund të krijojë një cikël të pafund.
Listat brenda një hapësire emrash
list_all dhe iterate faqosin të njëjtin endpoint si list pranë tyre, dhe po ashtu bëjnë edhe çiftet e tjera të emërtuara sipas listës që përshkojnë. Çdo çift merr të njëjtët filtra si lista e vet.
| Hapësira e emrave | Një faqe | Të gjitha faqet | Një nga një |
|---|---|---|---|
| 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 |
Faqe që mbartin më shumë
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']))Disa lista mbartin më shumë se një faqe të thjeshtë. contacts.list_people shton seen pranë items, hasMore dhe nextCursor, temp_mail.list_messages shton expiresAt, dhe addresses.list kthen addresses në vend të items, pranë unrestricted, domains, hasMore dhe nextCursor. Secila vazhdon gjithsesi me cursor= dhe përshkohet me list_all dhe iterate të vet.
Dy lista faqosin ndryshe. templates.list_sends numëron faqet: jepni page= dhe page_size=, dhe lexoni total, page dhe pageSize pranë items. imports.list_failures lihet ashtu siç e dërgon API-ja, {'object': 'list', 'data': [...], 'nextCursor': ...}, dhe vazhdon me after=, numrin në nextCursor. Asnjëra nuk ka list_all ose iterate.
Madhësitë e faqeve
Shumica e listave marrin një limit= nga 1 deri në 100 me parazgjedhje 25, dy numrat në PAGE_LIMITS (PAGE_LIMITS.MAX_LIMIT dhe PAGE_LIMITS.DEFAULT_LIMIT). contacts.list, audiences.list_contacts, broadcasts.list_recipients dhe listat e tracking pranojnë deri në 200 me parazgjedhje 50, ndërsa temp_mail.list_messages pranon deri në 50. Një vlerë jashtë intervalit refuzohet me një 422 në vend që të kufizohet.
Te AsyncOpenEmail
Klienti asinkron faqos në të njëjtën mënyrë. list dhe list_all thirren me await, ndërsa iterate kthen një iterator asinkron që e përshkoni me async for, pa await përpara thirrjes.
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())