Create an email list

Creates an empty email list and returns the new audience object with a server-assigned id.

Endpoint

POST https://api.dairo.app/v1/audiences

Creates an empty email list and returns the new audience object with a server-assigned id. name is required, trimmed, and capped at 120 characters — an empty or whitespace-only name is a 400; the optional description is stored as null when blank. New lists start with status: "active" and a memberCount of 0; populate them with a follow-up POST /v1/audiences/{audienceId}/members. A successful create responds 201. Requires the audiences:write scope.

Scope: audiences:write. Send the API key as a bearer token; Scopes lists what each one reaches.

Request

cURL

curl -X POST "https://api.dairo.app/v1/audiences" \
  -H "Authorization: Bearer $DAIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ada Lovelace"
  }'

Headers

Name	Type	Required	Description
`Idempotency-Key`	string	no	Optional idempotency key for safe retries of side-effecting operations. (max length 128)

Body

Required, application/json: AudienceCreateRequest.

Field	Type	Required	Description
`name`	string	yes	(min length 1)
`description`	string	no

Response

201 Created. Body: application/json, AudienceResponse.

Field	Type	Required	Description
`list`	Audience	yes

201

{
  "list": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Ada Lovelace",
    "description": null,
    "status": "string",
    "memberCount": null,
    "createdAt": "2026-10-19T09:30:00Z",
    "updatedAt": "2026-10-19T09:30:00Z"
  }
}

Errors

Every error has the same body, {"error": {"type", "code", "message", "param"}}; branch on code. Errors lists every code.

Status	Meaning
`400`	The request is malformed or a value is invalid (`invalid_request`, `invalid_domain`, `idempotency_key_mismatch`).
`401`	The API key is missing or invalid.
`403`	The key lacks the scope this endpoint needs (`scope_missing`) or may not do this (`not_permitted`).
`404`	No such resource in this account (`resource_not_found`).
`422`	The request is well-formed but a field failed validation (`validation_failed`).
`429`	Rate limit, plan limit, budget or spend cap reached (`rate_limited`, `plan_limit_reached`, `budget_exceeded`, `spend_cap_reached`).
`500`	An unexpected error; retry with backoff, then contact support (`internal_error`).