/v1/workspaces/{workspace_id}/topicsAuthCreate 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 · uuidId of the workspace.
Headers
Idempotency-KeystringOpaque 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*stringShown to recipients on the unsubscribe page.
Example: "Product updates"
descriptionstringOne 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 · uuidThe topic id.
name*stringDisplay name of the topic, shown on the unsubscribe page.
Example: "Product updates"
description*stringOptional longer text shown under the name on the unsubscribe page.
default_subscription*objectWhether 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-timeWhen the topic was created.
updated_at*string · date-timeWhen 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"
}