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

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 — the sending identity a campaign or flow actually sends through:

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

WhatsApp

Guides

Messaging Controls

Audience & Support Tools

Custom Opt-Out Keyword Lists

Custom Opt-Out Keyword Lists

When you need one

What you can and can’t change

Creating a list

Attaching a list to a messaging service

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

Endpoints

See also

​Custom Opt-Out Keyword Lists

​When you need one

​What you can and can’t change

​Creating a list

​Attaching a list to a messaging service

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

​Endpoints

​See also

Custom Opt-Out Keyword Lists

When you need one

What you can and can’t change

Creating a list

Attaching a list to a messaging service

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

Endpoints

See also