> ## Documentation Index
> Fetch the complete documentation index at: https://spotzee.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure subscription preferences

> Define subscription types per channel, then manage preferences through hosted links or server-side API calls.

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

> [!NOTE]
>
> 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:

| State | Meaning | Spotzee will send |
| - | - | - |
| `subscribed` | User has opted in | Yes |
| `unsubscribed` | User has opted out | No |
| `opted_in` | Explicit opt-in value accepted by the API | Yes; treated like `subscribed` for sends |

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.

```json theme={null}
[
  { "external_id": "user_001", "subscription_id": 12, "state": 0 },
  { "external_id": "user_002", "subscription_id": 12, "state": 1 },
  { "anonymous_id": "abc-123", "subscription_id": 13, "state": 1 }
]
```

Up to 100 toggles per request. Spotzee returns a per-item outcome list so you can retry only the failures.

## Unsubscribe links and SMS opt-out

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

> [card] [Set up a project](https://spotzee.com/docs/guides/setup-project.md)
>
> Configure SMS opt-out and help messages for keyword replies.

> [card] [Sync users](https://spotzee.com/docs/guides/sync-users.md)
>
> Push user data into a project.

> [card] [Manage API keys](https://spotzee.com/docs/guides/manage-api-keys.md)
>
> Issue a secret project key for server-side preference-centre calls.

> [card] [Authentication](https://spotzee.com/docs/guides/authentication.md)
>
> The conceptual model for `pk_` plus user session token combinations.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.