---
title: "Create an audience"
description: "Makes a new, empty audience and returns it with its id. `name` is trimmed and must then be 1 to 120 characters. `description` is optional free text for whoever reads the list later. Names are not checked for duplicates, because an audience is addressed by its id."
url: "https://openemail.uk/docs/api/audiences/create"
area: "API"
category: "Mailbox"
---

# Create an audience

Makes a new, empty audience and returns it with its id. `name` is trimmed and must then be 1 to 120 characters. `description` is optional free text for whoever reads the list later. Names are not checked for duplicates, because an audience is addressed by its id.

`POST /audiences`

## POST /audiences

Makes a new, empty audience and returns it with its id. `name` is trimmed and must then be 1 to 120 characters. `description` is optional free text for whoever reads the list later. Names are not checked for duplicates, because an audience is addressed by its id.

## Example

Needs `audiences:write`.

**curl**

```
curl -X POST "$OE/audiences" -H "$AUTH" -H 'content-type: application/json' -d '{
  "name": "Product updates",
  "description": "Customers who asked to hear about releases"
}'
```

**Response**

```
{
  "object": "audience",
  "id": "aud_4c1b8e2a7d9f05c36b4e8a71",
  "name": "Product updates",
  "description": "Customers who asked to hear about releases",
  "builtin": null,
  "contactCount": 0,
  "createdAt": "2026-09-18T09:10:00.000Z",
  "updatedAt": "2026-09-18T09:10:00.000Z"
}
```

> `builtin` is never accepted from the body. Exactly one row per workspace carries it and the server owns that row.

> A workspace holds at most 100 audiences. The next one is refused with `422` `audience_limit_reached` on `name`.

> Fill it with the add route, one contact at a time, and the contacts have to be in the book already.