Audiences

An audience is a list. Contacts, fields, segments and topics all live inside one.

Subscribers are unlimited on paid plans, because you pay per email sent. The free plan caps an account at 500; a contact write that would cross it is 403 plan_limit_reached.

The Audience object


{
  "id": "aud_7k2m9x4v0dz1",
  "object": "audience",
  "name": "Product newsletter",
  "contact_counts": {
    "subscribed": 4210,
    "unsubscribed": 130,
    "total": 4402
  },
  "created_at": "2026-01-15T09:30:00.000Z",
  "updated_at": "2026-06-01T14:00:00.000Z"
}

contact_counts is only on GET /audiences/{id}. It costs a count query, so the list omits it.

List audiences

GET/v1/audiences

Newest first, cursor-paginated.


curl https://go.day3.app/api/v1/audiences \
  -H "Authorization: Bearer $DAY3_API_KEY"


{
  "data": [
    {
      "id": "aud_7k2m9x4v0dz1",
      "object": "audience",
      "name": "Product newsletter",
      "created_at": "2026-01-15T09:30:00.000Z",
      "updated_at": "2026-06-01T14:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Create an audience

POST/v1/audiences

Field	Type	Required	Notes
`name`	string	Yes	1 to 100 characters.


curl -X POST https://go.day3.app/api/v1/audiences \
  -H "Authorization: Bearer $DAY3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Product newsletter" }'

Returns 201 with the Audience object.

Retrieve an audience

GET/v1/audiences/{audience_id}

Includes contact_counts: a count per status plus total.

Update an audience

PATCH/v1/audiences/{audience_id}

name is the only thing you can change.


curl -X PATCH https://go.day3.app/api/v1/audiences/aud_7k2m9x4v0dz1 \
  -H "Authorization: Bearer $DAY3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Changelog" }'

Delete an audience

DELETE/v1/audiences/{audience_id}

Deletes every contact, field, segment and topic inside it. Irreversible, no confirmation step. To stop mailing people, set their contacts to unsubscribed instead.


{ "id": "aud_7k2m9x4v0dz1", "deleted": true }

Suppressions are account-wide and survive.