Skip to main content
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)
Contact us to set up subscription management for your brand.

​
How it works

1

User sends keyword

Recipients can send one of the following keywords to your configured phone number:
KeywordAction
STOPUnsubscribe from marketing messages
STARTResubscribe to marketing messages
HELPRequest 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 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.