Topics

A topic is a subscription category inside an audience. A reader who only wants release notes can drop the rest instead of leaving the list.

Each topic has a default. A contact’s explicit choices are stored as deviations from it.

The Topic object


{
  "id": "top_789k4m2v0dz1",
  "object": "topic",
  "name": "Product updates",
  "description": "Release notes and changelogs",
  "default_subscribed": true,
  "created_at": "2026-02-20T09:00:00.000Z",
  "updated_at": "2026-02-20T09:00:00.000Z"
}

Field	Notes
`name`	Shown to subscribers on the preferences page.
`description`	Optional. Shown next to the name.
`default_subscribed`	Whether a contact with no explicit choice is in.

List topics

GET/v1/audiences/{audience_id}/topics

Create a topic

POST/v1/audiences/{audience_id}/topics


curl -X POST https://go.day3.app/api/v1/audiences/aud_123/topics \
  -H "Authorization: Bearer $DAY3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Product updates",
        "description": "Release notes and changelogs",
        "default_subscribed": true
      }'

Field	Type	Required	Notes
`name`	string	Yes
`description`	string	No
`default_subscribed`	boolean	No	Defaults to `true`.

default_subscribed: true opts your whole existing audience in, including people who never asked for this category. Fine for mail you already send. Not fine for a new promotional stream.

Retrieve a topic

GET/v1/audiences/{audience_id}/topics/{topic_id}

Update a topic

PATCH/v1/audiences/{audience_id}/topics/{topic_id}

name, description and default_subscribed. Changing the default only affects contacts with no explicit choice.

Delete a topic

DELETE/v1/audiences/{audience_id}/topics/{topic_id}

Removes the topic and every per-contact subscription to it. Contacts are untouched.


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

Per-contact subscriptions

These live on the contact:

GET /v1/audiences/{audience_id}/contacts/{id_or_email}/topics
PATCH /v1/audiences/{audience_id}/contacts/{id_or_email}/topics

GET returns the effective state, with an is_default flag per topic. PATCH takes a partial map; topics you leave out are untouched:


{ "topics": { "top_789": false, "top_790": true } }

Batch imports take the same map per item, so Mailchimp groups and interests carry across in one pass. See Contacts.