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

# Custom Opt-Out Keyword Lists

> Configure per-brand STOP, HELP, and START keywords and auto-response copy in Orbit, then attach the opt-out list to a messaging service for compliance.

# Custom Opt-Out Keyword Lists

Every Orbit tenant gets carrier-mandated STOP / HELP / START handling out of the box. An opt-out list lets you go further when you send under more than one brand or in more than one language: define extra keyword aliases and custom auto-response copy, then attach that list to the specific [messaging service](/api-reference/messaging-credentials) that should use it. A messaging service with no list attached keeps the platform defaults.

The full endpoint list is below; this page covers the concepts and how the fields are used.

## When you need one

Reach for a custom opt-out list when:

* You send under **multiple brands** from one Orbit account and want each brand's STOP reply to sound like that brand ("You're unsubscribed from Acme Travel alerts." vs. "You're unsubscribed from Acme Pharmacy reminders.").
* Your audience texts in a **language or dialect** whose opt-out word isn't covered by the platform defaults — you can add local aliases without losing the mandatory ones.
* You want **branded HELP text** ("Reply HELP for support, or call 1-800-…") instead of the generic default.

## What you can and can't change

The per-list keyword arrays are **additive only**. Orbit's matcher merges your list's keywords with the platform-default, carrier-mandated set — you can widen the trigger surface (add `"CANCEL"` or a local-language word alongside `STOP`) but you cannot remove `STOP` itself. TCPA and CTIA require it, and Orbit enforces that at the platform level regardless of what a tenant configures.

## Creating a list

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/messaging/opt-out-lists \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Acme Travel — ES",
    "stop_keywords": ["BAJA", "CANCELAR"],
    "help_keywords": ["AYUDA"],
    "stop_response": "Has cancelado las alertas de Acme Travel. Responde AYUDA para soporte.",
    "help_response": "Acme Travel: responde BAJA para cancelar, o llama al 1-800-555-0100.",
    "default_lang": "es",
    "brand": "Acme Travel"
  }'
```

| Field                                                | Notes                                                                                                 |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `label`                                              | Your name for the list, shown in the dashboard.                                                       |
| `stop_keywords` / `help_keywords` / `start_keywords` | Up to 32 entries each, additive on top of the platform defaults.                                      |
| `stop_response` / `help_response` / `start_response` | Auto-reply copy sent when the matching keyword fires, up to 1,600 characters (about 10 SMS segments). |
| `default_lang`                                       | One of `en`, `tr`, `de`, `es`, `fr`, `pt`, `it`, `ar`, `nl`.                                          |
| `brand`                                              | Free-text brand label used for your own reference and reporting.                                      |

## Attaching a list to a messaging service

A list only takes effect once it's attached to a [messaging service](/api-reference/messaging-credentials) — the sending identity a campaign or flow actually sends through:

```bash theme={null}
curl -X PATCH https://api.orbit.devotel.io/api/v1/messaging/services/msvc_abc123 \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "opt_out_list_id": "ool_abc123" }'
```

Every messaging service that should use the same branded keywords and copy points its `opt_out_list_id` at the same list. Detach it by setting `opt_out_list_id` to `null`, which falls back to the platform defaults for that service.

## Opt-out lists vs. suppression lists vs. contact opt-outs

These are three different layers and it's easy to mix them up:

* **Opt-out lists (this page)** configure *how a STOP/HELP/START reply is recognized and answered* — the keyword matching and auto-response layer.
* **[Opt-out & suppression lists](/compliance/opt-out-suppression)** cover the compliance-side bulk suppression list — bulk-importing addresses that must never be messaged again, e.g. when migrating off another platform.
* **[Opt-Outs API](/api-reference/optouts)** is the per-contact, per-channel record of who has actually opted out — the thing every send is checked against before dispatch.

A wider STOP keyword set (this page) increases how many inbound replies get *recognized* as an opt-out; the actual blocking happens through the contact opt-out record it writes.

## Endpoints

| Method   | Path                                   | Purpose                 |
| -------- | -------------------------------------- | ----------------------- |
| `GET`    | `/api/v1/messaging/opt-out-lists`      | List your opt-out lists |
| `POST`   | `/api/v1/messaging/opt-out-lists`      | Create a list           |
| `GET`    | `/api/v1/messaging/opt-out-lists/{id}` | Get a list              |
| `PATCH`  | `/api/v1/messaging/opt-out-lists/{id}` | Update a list           |
| `DELETE` | `/api/v1/messaging/opt-out-lists/{id}` | Delete a list           |

## See also

* [Opt-Out & Suppression Lists](/compliance/opt-out-suppression) — bulk suppression-list import
* [Opt-Outs API reference](/api-reference/optouts) — per-contact opt-out records
* [Messaging credentials & services](/api-reference/messaging-credentials) — attaching a list via `opt_out_list_id`