---
title: "List audiences"
description: "An audience is a named list of contacts in this workspace. Every contact is in the built-in default audience from the moment it exists, and `builtin` is what names that row; the rest are yours to make, fill and delete. The default audience comes first, then the rest newest first. Send to one or more of them with `POST /broadcasts`."
url: "https://nextmail.sh/docs/api/audiences/list"
area: "API"
category: "Mailbox"
---

# List audiences

An audience is a named list of contacts in this workspace. Every contact is in the built-in default audience from the moment it exists, and `builtin` is what names that row; the rest are yours to make, fill and delete. The default audience comes first, then the rest newest first. Send to one or more of them with `POST /broadcasts`.

`GET /audiences`

## GET /audiences

An audience is a named list of contacts in this workspace. Every contact is in the built-in default audience from the moment it exists, and `builtin` is what names that row; the rest are yours to make, fill and delete. The default audience comes first, then the rest newest first. Send to one or more of them with `POST /broadcasts`.

## Example

Needs `audiences:read`. `limit` goes up to 100 and defaults to 25, and `cursor` takes the previous page's `nextCursor`.

**curl**

```
curl "$OE/audiences" -H "$AUTH"
```

**Response**

```
{
  "object": "list",
  "data": [
    {
      "object": "audience",
      "id": "aud_9f2c4b7e1a0d63d84c5f2e7b",
      "name": "All contacts",
      "description": null,
      "builtin": "default",
      "contactCount": 412,
      "lastContactAt": "2026-09-18T09:30:00.000Z",
      "createdAt": "2026-08-01T10:00:00.000Z",
      "updatedAt": "2026-08-01T10:00:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}
```

> Branch on `builtin` rather than on the name. The default audience can be renamed by anybody, and its name is the only thing about it that changes.

> The default audience is resolved on the first read, so a workspace that has never made an audience still lists exactly one row.

> `contactCount` is counted at the moment of the read, so two reads either side of a create disagree by one. Names are not unique, so store ids rather than names.

## Reference

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