Mail API reference

Mail API · Topics

post/v1/workspaces/{workspace_id}/topicsAuth

Create a topic

Send on a topic with `topic_id` on a template send. Recipients manage their topics on the hosted unsubscribe page. At most 50 topics per workspace.

Path parameters

workspace_id*string · uuid

Id of the workspace.

Headers

Idempotency-Keystring

Opaque client-generated string (1–256 chars, `[A-Za-z0-9._:-]`) used to deduplicate retries within a 24h window. A retry with the same key and body returns the original response with `Idempotent-Replay: true`.

Request body

name*string

Shown to recipients on the unsubscribe page.

Example: "Product updates"

descriptionstring

One line under the name on the unsubscribe page.

default_subscription*enum (2)

`opt_in`: contacts receive the topic unless they opt out — but only contacts with a recorded consent (`consent` on the contact, or an import row that asserted it). `opt_out`: contacts receive it only after opting in. Fixed once created.

visibilityenum (2)

`public` topics are listed on the unsubscribe page; `private` ones are not (a recipient can still leave one from its own link).

Response · 201

id*string · uuid

The topic id.

name*string

Display name of the topic, shown on the unsubscribe page.

Example: "Product updates"

description*string

Optional longer text shown under the name on the unsubscribe page.

default_subscription*object

Whether a contact who never chose is subscribed (`opt_in`) or not (`opt_out`).

visibility*object

`public` topics appear on the unsubscribe page; `private` ones do not.

created_at*string · date-time

When the topic was created.

updated_at*string · date-time

When the topic was last changed.

Example

Request

POST https://api.mail.productcraft.co/v1/workspaces/{workspace_id}/topics
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "name": "Product updates",
  "description": "string",
  "default_subscription": "opt_in",
  "visibility": "public"
}

Response

{
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "Product updates",
  "description": "string",
  "default_subscription": {},
  "visibility": {},
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}