---
title: "List an audience's contacts"
description: "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."
url: "https://nextmail.sh/docs/api/audiences/contacts"
area: "API"
category: "Mailbox"
---

# 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.

`GET /audiences/{id}/contacts`

## 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**

```
curl "$OE/audiences/aud_4c1b8e2a7d9f05c36b4e8a71/contacts?q=grace&sort=added-newest&limit=50" -H "$AUTH"
```

**Response**

```
{
  "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.

## Reference

- [`GET /audiences/{id}/contacts`](https://nextmail.sh/docs/api/reference/audiences#get-audiences-id-contacts): full reference