List people
Everyone the Contacts page in the app lists: the saved contacts, and every address seen in mail as the sender or a recipient of a thread's newest message, with how many threads each shares with the mailbox and when mail last moved. A person seen in mail and saved is one row. Paging is keyset: `limit` goes up to 100 and defaults to 25, and `nextCursor` goes back as `cursor` while `hasMore` is true.
Runs the real call against your workspace, with your own key.
GET /contacts/people
Everyone the Contacts page in the app lists: the saved contacts, and every address seen in mail as the sender or a recipient of a thread's newest message, with how many threads each shares with the mailbox and when mail last moved. A person seen in mail and saved is one row. Paging is keyset: limit goes up to 100 and defaults to 25, and nextCursor goes back as cursor while hasMore is true.
Example
Needs contacts:read. The addresses seen in mail are included only when the key also holds threads:read.
curl "$OE/contacts/people?sort=threads&limit=25" -H "$AUTH"{ "object": "list", "data": [ { "object": "person", "email": "[email protected]", "displayEmail": "[email protected]", "name": "Ada Lovelace", "saved": true, "source": "manual", "notes": "Met at the engine demo", "photoUrl": null, "threads": 42, "lastAt": "2026-09-22T16:04:11.000Z", "createdAt": "2026-08-01T10:00:00.000Z", "updatedAt": "2026-09-01T09:12:00.000Z", "blockedBy": null }, { "object": "person", "email": "[email protected]", "displayEmail": "[email protected]", "name": "Shop", "saved": false, "source": null, "notes": null, "photoUrl": null, "threads": 17, "lastAt": "2026-09-21T07:30:00.000Z", "createdAt": null, "updatedAt": null, "blockedBy": { "rule": "shop.example", "list": "blockedDomains" } } ], "hasMore": true, "nextCursor": "WyIyMDI2LTA5LTIxVDA3OjMwOjAwLjAwMFoiLDE3XQ", "seen": true}sort is recent (the default), newest mail first with saved contacts never seen in mail after them, name, by name or else by address and ignoring case, or threads, most threads first. Ties fall back to the address, so a walk never repeats or skips a row.
q searches names, addresses and notes. email reads one address, which is how to fetch one person's thread count and last mail. blocked=true returns only the people the workspace blocklist blocks, whole-domain rules included, and blockedBy names the rule on every row.
Without threads:read the rows are the saved contacts alone and seen is false, because the rest are read out of the mail. Deleted addresses and the mailbox's own addresses are never listed. The cursor is opaque: pass it back with the same sort, q and blocked, and one that was not handed out is a 400 invalid_cursor.