Skip to main content
A subscription is a named opt-in channel a user can subscribe to or unsubscribe from. Most projects need at least one per delivery channel (Marketing email, Transactional SMS, Product push) and many add topic-level subscriptions on top. Spotzee separates subscription types (configured by admins) from subscription states (per-user values).
Subscription types live under Settings → Subscriptions and require the project admin role. Per-user state changes can come from hosted preference links, PATCH /users/{userId}/subscriptions, or the server-side bulk toggle endpoint.

​
What a subscription type is

Each subscription type carries three attributes:
  • Name. What users see in unsubscribe links and preference centres (for example, Marketing email, Promotional SMS, Product updates).
  • Channel. One of email, text (SMS), push, webhook, or in_app. A subscription is bound to exactly one channel.
  • Public visibility. When on, the subscription appears in the customer-facing preference centre. When off, the subscription is internal-only (you control state from the server).
You can create as many subscription types as your channel mix needs. Common patterns:
  • One per channel: Marketing email, Marketing SMS, Marketing push.
  • Topic-level: Newsletter, Product updates, Onboarding tips, Account alerts.
  • Tier-aware: Free-tier email, Premium-tier email (when content differs by plan).

​
The three states

Per-user, each subscription has one of three states: If a user has no recorded opt-out for a subscription type, Spotzee treats that user as subscribed. Public visibility controls whether the type appears in the preference centre; it does not change the default send state.

​
Create a subscription type

1

Open Settings → Subscriptions

Inside the project, open Settings and pick the Subscriptions tab.
2

Create a new subscription

Choose Create subscription, then complete:
  • Name (for example, Marketing email).
  • Channel (email, text, push, webhook, or in_app).
  • Public. Toggle on if users should see this subscription in their preference centre. Off for internal-only types.
3

Save

Save. The new type appears in the table with the channel badge and visibility flag. Existing users have no state for the new type until you set one or they interact with it.

​
Let users manage their own preferences

Spotzee’s hosted preference link shows public subscription types and lets a user update their own choices. Include {{preferencesUrl}} in an email template to give the recipient a route to that page. To build your own preference centre, keep a secret project key on your server. Use GET /users/{userId}/subscriptions to read the user’s states and PATCH /users/{userId}/subscriptions to update them. Do not expose the secret key in the browser.

​
Bulk-toggle from your server

When you need to flip subscription state across many users, use POST /subscriptions/batch with a secret key. Each item identifies its target by external_id or anonymous_id. Per-item errors are returned so a single failed lookup doesn’t hold up the rest of the batch.
Up to 100 toggles per request. Spotzee returns a per-item outcome list so you can retry only the failures. Some opt-out flows happen automatically:
  • Email unsubscribe links. Spotzee adds a List-Unsubscribe header to outbound email. Templates can render an unsubscribe link with {{unsubscribeEmailUrl}}. Following the link records unsubscribed for the campaign subscription.
  • SMS keywords. Inbound replies containing STOP unsubscribe the user from every SMS subscription in the project. Replies containing START resubscribe them. These handlers require an SMS provider with an inbound callback configured.
  • Help keywords. Replies containing HELP send the configured SMS help message when one is set. Help responses do not change subscription state.
These flows mean you don’t need to wire up unsubscribe handling yourself for the common cases. Reach for the API only when you’re building a richer preference centre or processing opt-outs from another source.

​
Next steps

Set up a project

Configure SMS opt-out and help messages for keyword replies.

Sync users

Push user data into a project.

Manage API keys

Issue a secret project key for server-side preference-centre calls.

Authentication

The conceptual model for pk_ plus user session token combinations.