Topics

A topic is a kind of email your contacts can choose to get, such as "Product updates" or "Weekly tips". Send a broadcast to a topic, and only the contacts who want that kind of email get it. Manage topics under Audience > Topics in the console.

How topics work

Each topic has a default that decides who gets it before a contact has chosen:

Once a contact chooses, their choice wins over the default. The default is fixed when you create the topic: changing it later would change what everyone who never chose receives. To change it, create a new topic.

Each topic is also public or private:

• Public topics are shown to every contact on their preference page.
• Private topics are shown only to contacts you put in them (their choice is on). They can switch one off, but nobody can find or join a private topic on their own. A private topic with the OPT_IN default is not shown to everyone just because everyone gets it.

A team can have up to 50 topics at a time, and can make 500 in all, deleted ones included. Each name is used once.

Send a broadcast to a topic

On a broadcast's Send to step, pick a topic under Topic (optional). The audience count updates to the people who get it, and the review screen names the topic before you send. With the API, pass topicId when you create or change a broadcast (POST /v1/broadcasts or PATCH /v1/broadcasts/{broadcastId}; the older /v1/campaigns paths work too). Notix then sends only to contacts in the broadcast's list (or segment) who are subscribed and get the topic.

Notix checks topics again for each batch it sends. Someone who switches a topic off while the broadcast is sending is skipped from then on.

You cannot delete a topic while a scheduled, sending or paused broadcast uses it. If a broadcast's topic is gone anyway, the broadcast is paused and does not send. It never falls back to the whole list.

Deleting a topic keeps every contact's choice on it. Create a topic with the same name and the same default to bring it back, opt-outs included. A topic with a new name is a new topic: everyone starts at its default, so do not delete a topic and make a new one just to rename it. Change its name instead.

How contacts choose

The unsubscribe link in every broadcast opens a page where the contact can switch each topic on or off, or unsubscribe from everything. There is no login: the signed link is the key, and it only works for that one contact. A changed or made-up link is refused.

You can also set a contact's choices from the console or the API. Only set what the person chose themselves.

A choice belongs to the person, not one contact book: it applies to your team's contacts with the same address. When a contact turns a topic off on their own page, Notix also skips that address for the topic in every other list, including copies of the contact added or imported later.

When a contact switches a topic off on their own page, that choice is theirs. Your team can't switch it back on from the dashboard or with an API key: the API answers 409. The choice is changed from the preference link in your emails. Like the unsubscribe link, that link is all it takes, so anyone who has a contact's link, a team member included, could change the choice for them. Don't open or share your contacts' links.

The opt-out is kept by email address, so it still applies if the contact is deleted and added again.

Topics with the API

curl -X POST https://app.usenotix.dev/api/v1/topics \
  -H "Authorization: Bearer $NOTIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product updates",
    "description": "New features, about once a month.",
    "defaultSubscription": "OPT_IN",
    "visibility": "PUBLIC"
  }'

import { Notix } from "notix-js";

const notix = new Notix(process.env.NOTIX_API_KEY);

const { data: topic } = await notix.topics.create({
  name: "Product updates",
  description: "New features, about once a month.",
  defaultSubscription: "OPT_IN",
  visibility: "PUBLIC",
});

notix.topics also has list, get, update and delete. See the Topics reference.

Read and set a contact's topics

GET /v1/contacts/{contactId}/topics returns every topic and where the contact stands on each. subscribed says whether a broadcast for that topic reaches them, and chosen is false when that is only the topic's default.

To record a choice, send up to 50 topics at once:

curl -X PATCH https://app.usenotix.dev/api/v1/contacts/ct_123/topics \
  -H "Authorization: Bearer $NOTIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "topics": [{ "topicId": "tp_123", "subscribed": false }] }'

await notix.topics.updateContactTopics("ct_123", {
  topics: [{ topicId: "tp_123", subscribed: false }],
});

const { data } = await notix.topics.getContactTopics("ct_123");

This never changes whether the contact unsubscribed from everything.

Topics for AI agents

An AI connected through MCP has the tools list_topics, get_topic, create_topic, update_topic, delete_topic, get_contact_topics and update_contact_topics.

Who can change topics

Creating, changing and deleting topics, and setting a contact's choices, needs a full access key. Topics belong to the whole team, so a key limited to one domain can use them too. Every key that reads can read topics, including a live AI key, which cannot change them.

In the console, any team member can create and change topics. Only a team admin can delete one.