API Reference

Create topic

POST /topics — create a subscription topic within a sending domain.

POST/topics

Body parameters

namestringrequired

Display name (max 255 chars).

default_subscriptionstringrequired

The default subscription preference for new contacts: opt_in (every contact receives the topic unless they explicitly unsubscribe from it) or opt_out (no contact receives the topic unless they explicitly subscribe). This value cannot be changed later.

visibilitystringoptional

Visibility of the topic on the preference page: public (all contacts can see and toggle it) or private (only contacts already opted in can see it). Defaults to private.

descriptionstringoptional

Optional description shown on the preference page (max 200 chars).

domainstringrequired

The sending domain this topic belongs to (one of your domains). Topic names are unique within a domain but freely reusable across domains. Passing audience_id is no longer accepted — pass domain.

import { MailBlastr } from 'mailblastr';

const mb = new MailBlastr('mb_xxxxxxxxx');

const { data, error } = await mb.topics.create({ "domain": "yourdomain.com", "name": "Product updates", "default_subscription": "opt_in" });
console.log({ data, error });

{
  "object": "topic",
  "id": "topic_9a2f...",
  "audience_id": "aud_3b1c...",
  "name": "Product updates",
  "description": null,
  "default_subscription": "opt_in",
  "visibility": "private",
  "created_at": "2026-06-25T10:00:00.000Z"
}