Concepts
Consent topics
How Sapagan decides whether a person may receive a message.
Before it sends a marketing message, Sapagan checks consent. Every grant and revoke is written to an append-only audit log with its source and time.
Topics#
A consent topic is a named permission, for example order_updates. A topic has a key (lower case letters, digits and underscores, starting with a letter), a mode and, optionally, a channel.
| Mode | Meaning |
|---|---|
opt_out | People are in unless they leave. |
opt_in | People are in only after they grant. |
Create topics with POST /v1/consent-topics and list them with GET /v1/consent-topics. The keys marketing and seller_marketing are reserved: the engine creates them.
Reading and writing consent#
GET /v1/customers/{id}/consent returns a person's choices. PUT /v1/customers/{id}/consent grants or revokes topics and sets the global unsubscribe. Only a workspace key can write consent. A store never can.
The body has a required source (settings, support, import or preference_center), optional ip and userAgent as evidence, a topics list of {scopeId, key, granted}, and unsubscribed. A change that changes nothing writes nothing.
An explicit revoke sticks. A later follow or order does not override it. Only an explicit grant lifts it.
Three levels of "stop"#
| Level | Effect |
|---|---|
This store's marketing topic | No messages from one store. |
seller_marketing | No messages from any store. |
Unsubscribed from everything (unsubscribedAt) | No marketing at all. |
In a marketplace, following a store or buying from it puts a person in that store's audience by default (setting follow_grants_scope_consent, on by default). People can switch off one store, all sellers, or everything, from any message and from the hosted preference center.
What consent does not stop#
Transactional messages reach a person who unsubscribed from marketing. They still respect a topic you name on the send, deleted and erased people, and suppressed addresses.
Email unsubscribe#
Every marketing email has a List-Unsubscribe header and a one-click unsubscribe, and a footer link to the preference center. Hard bounces and complaints add the address to the suppression list (GET /v1/suppressions).