Topics

Topics let subscribers opt out of specific content categories while staying on your list.

GET/api/v1/lists/{listId}/topics

Get all topics for a list. Cursor-paginated (per_page default 25, max 100; cursor for next/previous page).

Path Parameters

listIdinteger

required

The ID of the parent list.

Response Fields

idinteger

The topic ID.

uuidstring

The topic UUID.

list_idinteger

The parent list ID.

namestring

Topic name. Unique within the list.

descriptionstring|null

Optional description.

created_atstring

ISO 8601 creation timestamp.

metaobject

Cursor pagination metadata (path, per_page, next_cursor, prev_cursor).

Request

curl -X GET \
  "https://byomailer.com/api/v1/lists/{listId}/topics" \
  -H "Authorization: Bearer {your-api-token}" \
  -H "Accept: application/json"

Response

200

{
  "data": [
    {
      "id": 1,
      "uuid": "topic-uuid-1",
      "list_id": 10,
      "name": "Product Updates",
      "description": "Release notes and feature announcements",
      "created_at": "2026-04-15T10:30:00.000000Z"
    }
  ],
  "meta": {
    "path": "https://byomailer.com/api/v1/lists/10/topics",
    "per_page": 25,
    "next_cursor": null,
    "prev_cursor": null
  }
}

POST/api/v1/lists/{listId}/topics

Create a topic on a list. All existing contacts on the list are auto-subscribed to the new topic asynchronously via a background job.

Path Parameters

listIdinteger

required

The ID of the parent list.

Body Parameters

namestring

required

Human-readable topic name. Unique per list.

descriptionstring

Optional topic description.

Request

curl -X POST \
  "https://byomailer.com/api/v1/lists/{listId}/topics" \
  -H "Authorization: Bearer {your-api-token}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Product Updates",
  "description": "Release notes and feature announcements"
}'

Response

201

{
  "data": {
    "id": 2,
    "uuid": "topic-uuid-2",
    "list_id": 10,
    "name": "Product Updates",
    "description": "Release notes and feature announcements",
    "created_at": "2026-04-15T10:35:00.000000Z"
  }
}

PATCH/api/v1/lists/{listId}/topics/{topicId}

Update a topic.

Path Parameters

listIdinteger

required

The ID of the parent list.

topicIdinteger

required

The ID of the topic.

Body Parameters

namestring

required

Updated name.

descriptionstring

Updated description.

Request

curl -X PATCH \
  "https://byomailer.com/api/v1/lists/{listId}/topics/{topicId}" \
  -H "Authorization: Bearer {your-api-token}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Product News",
  "description": null
}'

Response

200

{
  "data": {
    "id": 2,
    "uuid": "topic-uuid-2",
    "list_id": 10,
    "name": "Product News",
    "description": null,
    "created_at": "2026-04-15T10:35:00.000000Z"
  }
}

DELETE/api/v1/lists/{listId}/topics/{topicId}

Delete a topic and all subscription state for it.

Path Parameters

listIdinteger

required

The ID of the parent list.

topicIdinteger

required

The ID of the topic.

Request

curl -X DELETE \
  "https://byomailer.com/api/v1/lists/{listId}/topics/{topicId}" \
  -H "Authorization: Bearer {your-api-token}" \
  -H "Accept: application/json"

Response

204

No content