Skip to main content
A topic is a mailing list you attribute a send to, such as a newsletter, a product-update list, or a receipts stream. Recipients manage their preferences per topic, and mailkube filters a send against those preferences for you. Topics belong to your organization and are scoped to your sending domain’s apex: mail.acme.com and news.acme.com share the same topics under acme.com. Subdomains of a shared hosting suffix are each their own apex, and never share a topic pool. Attributing a send to a topic is optional. A send with no topic is delivered as-is.

Opt-in vs opt-out

Every topic has a type that decides how it affects a send:
A preference is held per recipient and per topic, never account-wide. Unsubscribing from one topic never affects another, and a topic on one apex is independent of a same-named topic on another.

What happens on a send

When you name a topic on a send:
  • An unknown or disabled topic rejects the send before it is charged against your quota. Fix the topic reference and retry. (REST: a topic_not_found or topic_disabled error; SMTP: a 550 5.7.1 reply, see Error codes.)
  • A recipient who unsubscribed from an opt-out topic is dropped before delivery. The send is accepted and counts against your quota, exactly like the suppression of a hard-bounced address. You can observe it on the email.suppressed webhook.
  • Every other recipient is delivered to normally.
The two channels scope that drop differently. SMTP drops the individual envelope recipient and delivers to the rest. REST evaluates to, cc and bcc as one set, so a single unsubscribed address drops the whole message for everyone on it.A REST send dropped this way still answers 200 with an id. That id is minted for the response and is not the email_id carried by the email.suppressed event, so the two cannot be correlated.
A topic slug is at most 16 characters. mailkube slugifies whatever value you send before matching it, so Product News, product news and product-news all resolve to the same topic.The stored slug is not always the name lowercased. A name over 16 characters is truncated, and a name whose slug is already taken on the apex gets a numeric suffix. Read the slug off the dashboard rather than deriving it from the name.

Attributing a send to a topic

Both take the topic slug and resolve it to your sending domain’s apex.