Worked samples and errors worth branching on

curl -X POST https://api.orbit.devotel.io/api/v1/messaging/opt-out-lists \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Acme FR — STOP/HELP",
    "stop_keywords": ["STOP", "ARRET"],
    "help_keywords": ["HELP"],
    "start_keywords": ["START"],
    "stop_response": "Vous êtes désinscrit des alertes Acme. Répondez START pour vous réinscrire.",
    "help_response": "Acme : répondez STOP pour vous désinscrire. Support : support@acme.example",
    "start_response": "Vous êtes réinscrit aux alertes Acme.",
    "default_lang": "fr",
    "brand": "acme-fr"
  }'

{
  "data": {
    "id": "optout-list_01h8d2kqv7wqa",
    "label": "Acme FR — STOP/HELP",
    "stop_keywords": ["STOP", "ARRET"],
    "help_keywords": ["HELP"],
    "start_keywords": ["START"],
    "stop_response": "Vous êtes désinscrit des alertes Acme. Répondez START pour vous réinscrire.",
    "help_response": "Acme : répondez STOP pour vous désinscrire. Support : support@acme.example",
    "start_response": "Vous êtes réinscrit aux alertes Acme.",
    "default_lang": "fr",
    "brand": "acme-fr",
    "deleted": false,
    "created_at": "2026-09-11T12:00:00.000Z",
    "updated_at": "2026-09-11T12:00:00.000Z"
  },
  "meta": {
    "request_id": "req_optout_create",
    "timestamp": "2026-09-11T12:00:00Z"
  }
}

curl -X POST https://api.orbit.devotel.io/api/v1/messaging/opt-out-lists \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Acme FR — STOP/HELP",
    "stop_keywords": ["STOP", "ARRET"],
    "help_keywords": ["HELP"],
    "start_keywords": ["START"],
    "stop_response": "Vous êtes désinscrit des alertes Acme. Répondez START pour vous réinscrire.",
    "help_response": "Acme : répondez STOP pour vous désinscrire. Support : support@acme.example",
    "start_response": "Vous êtes réinscrit aux alertes Acme.",
    "default_lang": "fr",
    "brand": "acme-fr"
  }'

{
  "data": {
    "id": "optout-list_01h8d2kqv7wqa",
    "label": "Acme FR — STOP/HELP",
    "stop_keywords": ["STOP", "ARRET"],
    "help_keywords": ["HELP"],
    "start_keywords": ["START"],
    "stop_response": "Vous êtes désinscrit des alertes Acme. Répondez START pour vous réinscrire.",
    "help_response": "Acme : répondez STOP pour vous désinscrire. Support : support@acme.example",
    "start_response": "Vous êtes réinscrit aux alertes Acme.",
    "default_lang": "fr",
    "brand": "acme-fr",
    "deleted": false,
    "created_at": "2026-09-11T12:00:00.000Z",
    "updated_at": "2026-09-11T12:00:00.000Z"
  },
  "meta": {
    "request_id": "req_optout_create",
    "timestamp": "2026-09-11T12:00:00Z"
  }
}

Worked request and response samples

1) Create a custom opt-out list

One call equips a brand’s keyword aliases and auto-reply copy. The French opt-out vocabulary is the worked example — adding ARRET alongside the platform-mandated STOP, per-keyword auto-reply copy, and a brand tag so the reply text feels local to the audience:

POST /api/v1/messaging/opt-out-lists

curl -X POST https://api.orbit.devotel.io/api/v1/messaging/opt-out-lists \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Acme FR — STOP/HELP",
    "stop_keywords": ["STOP", "ARRET"],
    "help_keywords": ["HELP"],
    "start_keywords": ["START"],
    "stop_response": "Vous êtes désinscrit des alertes Acme. Répondez START pour vous réinscrire.",
    "help_response": "Acme : répondez STOP pour vous désinscrire. Support : support@acme.example",
    "start_response": "Vous êtes réinscrit aux alertes Acme.",
    "default_lang": "fr",
    "brand": "acme-fr"
  }'

{
  "data": {
    "id": "optout-list_01h8d2kqv7wqa",
    "label": "Acme FR — STOP/HELP",
    "stop_keywords": ["STOP", "ARRET"],
    "help_keywords": ["HELP"],
    "start_keywords": ["START"],
    "stop_response": "Vous êtes désinscrit des alertes Acme. Répondez START pour vous réinscrire.",
    "help_response": "Acme : répondez STOP pour vous désinscrire. Support : support@acme.example",
    "start_response": "Vous êtes réinscrit aux alertes Acme.",
    "default_lang": "fr",
    "brand": "acme-fr",
    "deleted": false,
    "created_at": "2026-09-11T12:00:00.000Z",
    "updated_at": "2026-09-11T12:00:00.000Z"
  },
  "meta": {
    "request_id": "req_optout_create",
    "timestamp": "2026-09-11T12:00:00Z"
  }
}

The returned id is what a messaging service stores in its opt_out_list_id. Per-keyword arrays stay under the caps: 32 entries per keyword kind, 64 chars per keyword, 1600 chars per auto-reply.

2) Read the list back — arrays are additive, never narrowing

A GET shows exactly what the list adds. The tenant-owned arrays only WIDEN the trigger surface on top of the platform-mandated STOP / HELP / START sets — tenant lists can never remove or replace them. TCPA and CTIA require the mandatory keywords to stay live, and the matcher enforces that at the platform level, whatever any list configures.

GET /api/v1/messaging/opt-out-lists/{id}

curl -X GET https://api.orbit.devotel.io/api/v1/messaging/opt-out-lists/optout-list_01h8d2kqv7wqa \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

{
  "data": {
    "id": "optout-list_01h8d2kqv7wqa",
    "label": "Acme FR — STOP/HELP",
    "stop_keywords": ["STOP", "ARRET"],
    "help_keywords": ["HELP"],
    "start_keywords": ["START"],
    "stop_response": "Vous êtes désinscrit des alertes Acme. Répondez START pour vous réinscrire.",
    "help_response": "Acme : répondez STOP pour vous désinscrire. Support : support@acme.example",
    "start_response": "Vous êtes réinscrit aux alertes Acme.",
    "default_lang": "fr",
    "brand": "acme-fr",
    "deleted": false,
    "created_at": "2026-09-11T12:00:00.000Z",
    "updated_at": "2026-09-11T12:00:00.000Z"
  },
  "meta": {
    "request_id": "req_optout_get",
    "timestamp": "2026-09-11T12:00:00Z"
  }
}

3) Attach the list to a messaging service

Until it is attached, a list has no effect — point the messaging service’s opt_out_list_id at the id saved from step 1 (the same attach call outlined on the messaging credentials page):

PATCH /api/v1/messaging/services/{id}

curl -X PATCH https://api.orbit.devotel.io/api/v1/messaging/services/msvc_01h8d3nrx9t \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "opt_out_list_id": "optout-list_01h8d2kqv7wqa" }'

After attachment, every inbound keyword match through that service merges this list’s arrays with the platform defaults. Detach by setting "opt_out_list_id": null; the service falls back to the platform-mandated keywords alone.

4) Update aliases — replace the array with the full intended set

Keyword arrays replace wholesale on PATCH, so adding an alias means resending the existing entries plus the new one. The response echoes the complete new set:

PATCH /api/v1/messaging/opt-out-lists/{id}

curl -X PATCH https://api.orbit.devotel.io/api/v1/messaging/opt-out-lists/optout-list_01h8d2kqv7wqa \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "stop_keywords": ["STOP", "ARRET", "ANNULER"] }'

{
  "data": {
    "id": "optout-list_01h8d2kqv7wqa",
    "label": "Acme FR — STOP/HELP",
    "stop_keywords": ["STOP", "ARRET", "ANNULER"],
    "help_keywords": ["HELP"],
    "start_keywords": ["START"],
    "stop_response": "Vous êtes désinscrit des alertes Acme. Répondez START pour vous réinscrire.",
    "help_response": "Acme : répondez STOP pour vous désinscrire. Support : support@acme.example",
    "start_response": "Vous êtes réinscrit aux alertes Acme.",
    "default_lang": "fr",
    "brand": "acme-fr",
    "deleted": false,
    "created_at": "2026-09-11T12:00:00.000Z",
    "updated_at": "2026-09-11T13:00:00.000Z"
  },
  "meta": {
    "request_id": "req_optout_update",
    "timestamp": "2026-09-11T13:00:00Z"
  }
}

5) Tenant-facing limitation — STOP / HELP / START are platform-mandated

The list is a tenant-owned, additive-only control. You widen the trigger surface (above, "ANNULER" joins the platform-mandated STOP). Dropping every custom alias still leaves the platform set intact and matching. You cannot narrow the mandatory sets — TCPA / CTIA require them to stay live, and the keyword matcher enforces that for any tenant configuration. Follow the guide at guides/opt-out-lists; do not build client logic that tries to subtract keywords.

Errors worth branching on

These failures cover the list lifecycle plus the opt-out add (POST /api/v1/opt-out-lists//entries), hammered from inbound STOP handlers. Each block below is a full { error, meta } envelope as the API returns it, and the matrix at the bottom answers retry vs surface for each class. For the platform-wide decision table these branches plug into, see the error handling guide.

401 — Unauthorized

  {
    "error": {
      "code": "UNAUTHORIZED",
      "message": "The API key is invalid, expired, or lacks the required scope.",
      "status": 401
    },
    "meta": {
      "request_id": "req_optoutlia1",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 401 on this page is the bearer key failing before the route ran — it never means the resource is wrong. Rotate the key or re-mint the scoped token; retrying the same request changes nothing.

403 — Forbidden

  {
    "error": {
      "code": "FORBIDDEN",
      "message": "The key is valid but does not have the scope this operation requires.",
      "status": 403
    },
    "meta": {
      "request_id": "req_optoutlia1f",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 403 means the key authenticated but the operation is gated by scope — check the key’s scopes on the developer page; a 403 is never a data-not-found shape.

422 — Schema

  {
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "The request failed input validation.",
      "status": 422,
      "details": { "field": "recipient", "value": "+1 415 555 2671", "expected": "an E.164 MSISDN with no spaces" }
    },
    "meta": {
      "request_id": "req_optoutlib2",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 422 means the payload did not match the request schema — branch on error.details.field and resend with the recipient in E.164 form instead of blind-retrying the same body.

429 — Rate

  {
    "error": {
      "code": "RATE_LIMITED",
      "message": "Too many requests in the current window.",
      "status": 429,
      "details": { "retry_after": 12 }
    },
    "meta": {
      "request_id": "req_optoutlic3",
      "timestamp": "2026-09-03T12:00:00Z",
      "docs_url": "https://docs.orbit.devotel.io/errors/RATE_LIMITED"
    }
  }

The Retry-After header and error.details.retry_after are both set on every 429 — resend the SAME request after the lower of the two.

409 — Conflict

  {
    "error": {
      "code": "OPT_OUT_ALREADY_SET",
      "message": "This recipient is already on the list.",
      "status": 409,
      "details": { "recipient": "+14155552671" }
    },
    "meta": {
      "request_id": "req_optoutlid4",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

Treat as a no-op — the suppression already took; do not surface it as a send-stopper.

409 — Label conflict

A second shape of 409, distinct from the entry-add conflict above: POST (or PATCH with a new label) names a label an active list in this tenant already uses. Labels are unique among active lists, and soft-deleting a list frees its label for reuse.

  {
    "error": {
      "code": "OPT_OUT_LIST_LABEL_CONFLICT",
      "message": "label 'Acme FR — STOP/HELP' is already used by an active opt-out list in this tenant",
      "status": 409,
      "details": { "label": "Acme FR — STOP/HELP" }
    },
    "meta": {
      "request_id": "req_optoutlie5",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

Pick a distinct label (or rename the conflicting list) and resend — a blind retry repeats the same 409.

60-second retry matrix

Class	Meaning	Branch response
401 `UNAUTHORIZED`	the bearer key itself fails	Surface. Rotate the key or re-mint the scoped token; do not retry the same request.
403 `FORBIDDEN`	the key lacks this operation’s scope	Surface. Fix the key’s scope set; a retry with the same key never heals it.
422 `VALIDATION_ERROR`	the payload does not match the schema	Fix, then resend intentionally. Branch on `error.details.field`; a blind retry repeats the same 422.
429 `RATE_LIMITED`	the window quota is exhausted	Retry after `error.details.retry_after` (or the `Retry-After` header) with the same request body.
`OPT_OUT_ALREADY_SET` (409 conflict)	Treat as a no-op	Branch on `error.code`. The suppression already took; do not surface it as a send-stopper.
`OPT_OUT_LIST_LABEL_CONFLICT` (409 conflict)	the label is taken by an active list	Fix, then resend. Pick a distinct label (or rename / soft-delete the conflicting list first); a blind retry repeats the same 409.

API Reference

All Endpoints

Worked request and response samples

1) Create a custom opt-out list

2) Read the list back — arrays are additive, never narrowing

3) Attach the list to a messaging service

4) Update aliases — replace the array with the full intended set

5) Tenant-facing limitation — STOP / HELP / START are platform-mandated

Errors worth branching on

401 — Unauthorized

403 — Forbidden

422 — Schema

429 — Rate

409 — Conflict

409 — Label conflict

60-second retry matrix

​Worked request and response samples

​1) Create a custom opt-out list

​2) Read the list back — arrays are additive, never narrowing

​3) Attach the list to a messaging service

​4) Update aliases — replace the array with the full intended set

​5) Tenant-facing limitation — STOP / HELP / START are platform-mandated

​Errors worth branching on

​401 — Unauthorized

​403 — Forbidden

​422 — Schema

​429 — Rate

​409 — Conflict

​409 — Label conflict

​60-second retry matrix

Worked request and response samples

1) Create a custom opt-out list

2) Read the list back — arrays are additive, never narrowing

3) Attach the list to a messaging service

4) Update aliases — replace the array with the full intended set

5) Tenant-facing limitation — STOP / HELP / START are platform-mandated

Errors worth branching on

401 — Unauthorized

403 — Forbidden

422 — Schema

429 — Rate

409 — Conflict

409 — Label conflict

60-second retry matrix