> ## 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 us](mailto:support@prelude.so) to set up subscription management for your brand.
</Info>

## How it works

<Steps>
  <Step title="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.
  </Step>

  <Step title="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)
  </Step>

  <Step title="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
  </Step>
</Steps>

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

Prelude 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>