Subscription Management

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)

How it works

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.

Prelude processes the request

When a user sends a keyword:

The subscription status is automatically updated in Prelude’s system
A confirmation message is sent back to the user
A webhook event is sent to your callback URL (if configured)

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 for details. Example STOP event:

{
  "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 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:

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

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

Documentation

API Reference

Subscription Management

Overview

How it works

Webhook events

Carrier disconnects

Confirmation messages

Default messages

Custom messages

API error handling

​Overview

​How it works

​Webhook events

​Carrier disconnects

​Confirmation messages

​Default messages

​Custom messages

​API error handling

Overview

How it works

Webhook events

Carrier disconnects

Confirmation messages

Default messages

Custom messages

API error handling