List an audience's contacts
The contacts themselves rather than membership records, each with `addedAt`, the moment it joined this audience. By default they come in the same order as the contacts list: most recently seen first, with contacts that have never been mailed last. `limit` goes up to 200 and defaults to 50, and `cursor` takes the previous page's `nextCursor`, so every contact in the audience is reachable. Reading the default audience here returns the whole address book.
Runs the real call on your workspace.
GET /audiences/{id}/contacts
The contacts themselves rather than membership records, each with addedAt, the moment it joined this audience. By default they come in the same order as the contacts list: most recently seen first, with contacts that have never been mailed last. limit goes up to 200 and defaults to 50, and cursor takes the previous page's nextCursor, so every contact in the audience is reachable. Reading the default audience here returns the whole address book.
Example
Needs audiences:read alone, without contacts:read.
curl "$OE/audiences/aud_4c1b8e2a7d9f05c36b4e8a71/contacts?q=grace&sort=added-newest&limit=50" -H "$AUTH"{ "object": "list", "data": [ { "object": "contact", "email": "grace@example.com", "name": "Grace Hopper", "source": "manual", "notes": null, "lastSeenAt": null, "createdAt": "2026-09-18T09:00:00.000Z", "updatedAt": "2026-09-18T09:00:00.000Z", "addedAt": "2026-09-18T09:30:00.000Z", "unsubscribedAt": null } ], "hasMore": false, "nextCursor": null, "audienceId": "aud_4c1b8e2a7d9f05c36b4e8a71"}A key holding audiences:read reads the addresses in an audience without holding contacts:read. Issue it deliberately.
unsubscribedAt is when the contact followed the unsubscribe link in a broadcast sent to this audience, and null while it is subscribed. An unsubscribed contact stays in the audience and in the book, and broadcasts to the audience skip it. An unsubscribe belongs to the whole workspace, so it marks every audience the person is in, and removing them and adding them back, deleting the contact or importing the address again keeps them unsubscribed. GET /suppressions/unsubscribes lists everyone who left.
A contact in no audience of your own is still in the default one, so nothing in the book is invisible to this route.
q searches the name and the address, up to 200 characters. When nothing matches exactly on the first page, close spellings are returned instead, and the pages that follow keep matching the same way. source is manual or auto, the same values as on the contacts list.
sort is last-heard-newest (the default), last-heard-oldest, added-newest, added-oldest or name. last-heard-oldest puts contacts that have never been mailed first, the two added orders go by addedAt in this audience, and name ignores case and sorts a contact with no name by its address.
Send the same q, source and sort with every cursor. A cursor naming a contact that is not in this audience is a 400 invalid_cursor. Walking every page is how to export an audience, since each row carries the name, lastSeenAt and addedAt.
status is subscribed, unsubscribed or both, comma-separated, and keeps only the members in that state. Leaving it out, or naming both, lists everyone. Send it with every cursor too.
Google Workspace
Fastmail