SapaganDocs sapagan.com

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.

ModeMeaning
opt_outPeople are in unless they leave.
opt_inPeople 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.

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"#

LevelEffect
This store's marketing topicNo messages from one store.
seller_marketingNo 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.

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).