Get an email list and its members
Returns one active email list as an audience object with its members inlined as a members array of audience_member objects, each carrying the recipient handle, optional contactId, name, metadata, source, and status.
Returns one active email list as an audience object with its members inlined as a members array of audience_member objects, each carrying the recipient handle, optional contactId, name, metadata, source, and status. Members are ordered by address and capped at 5000 in this view — for a larger list the member array is truncated, though a broadcast still reaches every active member. An unknown, archived, or cross-project audienceId is a 404. Requires the audiences:read scope.
Scope: audiences:read. Send the API key as a bearer token; Scopes lists what each one reaches.
Request
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
audienceId | string (uuid) | yes | The audience's ID. |
Response
200 Success. Body: application/json, AudienceDetailResponse.
| Field | Type | Required | Description |
|---|---|---|---|
object | "audience" | no | |
id | string (uuid) | yes | |
name | string | yes | |
description | string or null | no | |
status | string | yes | |
memberCount | integer or null | no | |
createdAt | string (date-time) | yes | |
updatedAt | string (date-time) | yes | |
members | array of AudienceMember | yes |
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). |
Create an email list
Creates an empty email list and returns the new audience object with a server-assigned id.
Archive an email list
Archives an email list by setting its status to archived; the list and its members are retained but the list no longer appears in GET /v1/audiences and can no longer be fetched or broadcast to.