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

# Subscription Management

> Manage user subscriptions and opt-out preferences for marketing messages with built-in STOP/START/HELP keyword support.

Prelude provides built-in subscription management for marketing messages, allowing recipients to easily opt-out and opt-in using standard keywords. This ensures compliance with regulations like TCPA (US) and GDPR (EU).

## Overview

Subscription management is configured per brand by our Customer Success team. Each configuration includes:

* **Short codes or long codes** for receiving opt-out requests
* **Callback URL** for receiving subscription events
* **Custom messages** for STOP, START, and HELP responses (optional)

<Info>
  Contact your Customer Success Manager to set up subscription management for your brand. Alternatively, reach out to Prelude support at [support@prelude.so](mailto:support@prelude.so).
</Info>

## How it works

### 1. User sends keyword

Recipients can send one of the following keywords to your configured phone number:

| Keyword | Action                                |
| ------- | ------------------------------------- |
| `STOP`  | Unsubscribe from marketing messages   |
| `START` | Resubscribe to marketing messages     |
| `HELP`  | Request information about the service |

Keywords are case-insensitive and must appear at the start of the message.

### 2. Prelude processes the request

When a user sends a keyword:

1. The subscription status is **automatically updated** in Prelude's system
2. A **confirmation message** is sent back to the user
3. A **webhook event** is sent to your callback URL (if configured)

### 3. Automatic enforcement

Once a user unsubscribes:

* Future API calls to send marketing messages to that number will return an error
* The user will **not** receive any marketing messages until they opt back in
* Transactional messages are **not affected** by subscription status

## Webhook events

You'll receive webhook events for all subscription changes. See the [Webhook documentation](/notify/v2/documentation/webhook#subscription-management-events) for details.

Example STOP event:

```json theme={null}
{
  "id": "evt_01k8aq2zggeyssvt53zgvpx63a",
  "type": "marketing.subscription.stop",
  "payload": {
    "action": "STOP",
    "from": "+33612345678",
    "to": "36184",
    "received_at": "2025-10-24T08:59:10.736909995Z"
  },
  "created_at": "2025-10-24T08:59:10.736925502Z"
}
```

### Carrier disconnects

Phone numbers that are detected as disconnected by the carrier are automatically unsubscribed from all subscription management configs. A `marketing.subscription.carrier_disconnect` event is sent to each config's callback URL. See the [Webhook documentation](/notify/v2/documentation/webhook#carrier-disconnect-events) for the event payload and handling guidance.

## Confirmation messages

When a user sends a keyword, they automatically receive a confirmation message:

### Default messages

If you don't configure custom messages, Prelude uses standard defaults:

**STOP response:**

```
You have been unsubscribed and will not receive further messages. Reply START to resubscribe.
```

**START response:**

```
You have been resubscribed and will receive messages again. Reply STOP to unsubscribe.
```

**HELP response:**

```
Reply STOP to unsubscribe or START to resubscribe.
```

### Custom messages

Your Customer Success Manager can configure custom messages for your brand to match your voice and include additional information like support contact details.

## API error handling

When you attempt to send a marketing message to an unsubscribed user, the API will return an error:

```json theme={null}
{
    "code": "unsubscribed",
    "message": "The provided phone number is unsubscribed.",
    "type": "bad_request",
    "request_id": "cb16bdf1-0501-4a90-a944-3144f6402112"
}
```

<Warning>
  Always handle the `unsubscribed` error in your application logic. Attempting to circumvent subscription preferences violates regulations and our terms of service.
</Warning>