Vobiz Messaging Opt-outs

An opt-out is a number that must not receive messages from your account on a channel. Vobiz builds the list for you from keyword replies and lets you add to it, query it and remove from it by API. Every send - single messages and broadcasts alike - is checked against the list before anything leaves the platform. The console shows the same list under SMS & RCS → Opt-outs.

Honouring opt-outs is a legal requirement in most markets (for example TCPA and CTIA guidelines in the US, and TRAI rules in India) and a condition of US 10DLC and toll-free registration. Keep the list intact, and make sure your own records of consent match it.

Keyword replies are recorded automatically

When a contact replies to one of your numbers, Vobiz lower-cases and trims the text, strips trailing punctuation, and compares it with the standard keywords. An exact match creates an opt-out entry for that number and channel with source: "inbound" and the reason shown:

Keyword reply	Recorded `reason`	Meaning
`STOP`, `UNSUBSCRIBE`, `CANCEL`, `END`	`stop`	The contact asked to receive no more messages.
`START`, `SUBSCRIBE`, `UNSTOP`	`start`	The contact asked to receive messages again.
`HELP`, `INFO`	`help`	The contact asked what the number is and how to stop.

All three groups are recorded automatically, so you have a timestamped record of every keyword interaction. The reply itself is also stored in the contact’s conversation, where you can see it in context.

When a contact replies START, remove their opt-out entry with Remove an opt-out once you have confirmed their consent, so that sends to them succeed again.

Keyword matching is exact: STOP and stop. match, please stop does not. Add a manual opt-out for any request that arrives in free text.

Add an opt-out manually

Create an opt-out records a request that reached you another way - a support call, an email, an unsubscribe link:

curl -X POST "https://api.vobiz.ai/api/v1/sms/opt-outs" \
  -H "X-Auth-ID: MA_XXXXXXXX" \
  -H "X-Auth-Token: YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "phoneNumber": "+14155550123", "channel": "sms", "reason": "support-request" }'

import requests

resp = requests.post(
    "https://api.vobiz.ai/api/v1/sms/opt-outs",
    headers={
        "X-Auth-ID": "MA_XXXXXXXX",
        "X-Auth-Token": "YOUR_AUTH_TOKEN",
        "Content-Type": "application/json",
    },
    json={"phoneNumber": "+14155550123", "channel": "sms", "reason": "support-request"},
)
resp.raise_for_status()
print(resp.status_code, resp.json())

const resp = await fetch("https://api.vobiz.ai/api/v1/sms/opt-outs", {
  method: "POST",
  headers: {
    "X-Auth-ID": "MA_XXXXXXXX",
    "X-Auth-Token": "YOUR_AUTH_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ phoneNumber: "+14155550123", channel: "sms", reason: "support-request" }),
});
console.log(resp.status, await resp.json());

Field	Required	Notes
`phoneNumber`	yes	E.164 with a leading `+`. Missing it returns `400 {"error":"phoneNumber is required"}`.
`channel`	no	`sms` (default), `mms` or `rcs`.
`reason`	no	Free text for your records. Default `manual`.

Response - 201 Created

{ "status": "ok" }

The entry is keyed on number and channel. Adding the same number again updates its reason rather than creating a duplicate. Manual entries have source: "manual".

List opt-outs

List opt-outs returns a JSON array of entries. Both limit and offset are required; page through the list by increasing offset.

cURL

curl "https://api.vobiz.ai/api/v1/sms/opt-outs?limit=100&offset=0" \
  -H "X-Auth-ID: MA_XXXXXXXX" \
  -H "X-Auth-Token: YOUR_AUTH_TOKEN"

Response - 200 OK

[
  {
    "id": "9b2e1c40-8a3d-4f5e-9c1a-7d6b2e8f4a01",
    "accountId": "MA_XXXXXXXX",
    "phoneNumber": "+14155550123",
    "channel": "sms",
    "reason": "stop",
    "source": "inbound",
    "syncedToProvider": true,
    "createdAt": "2026-10-18T07:23:03.658669Z"
  },
  {
    "id": "3c1d7e52-6f4b-4a8e-b2d9-0e5f1a7c9b34",
    "accountId": "MA_XXXXXXXX",
    "phoneNumber": "+14155550124",
    "channel": "sms",
    "reason": "support-request",
    "source": "manual",
    "syncedToProvider": true,
    "createdAt": "2026-10-17T15:02:11.104233Z"
  }
]

Field	Meaning
`phoneNumber`	The opted-out number.
`channel`	The channel the entry applies to.
`reason`	`stop`, `start` or `help` for keyword entries; `manual` or your own text for API entries.
`source`	`inbound` (keyword reply) or `manual` (API or console).
`syncedToProvider`	Whether the entry has also been propagated to the upstream network’s suppression list.
`createdAt`	When the entry was recorded or last updated.

Check one number

Check an opt-out answers a yes/no question for one number and channel. URL-encode the + as %2B. channel defaults to sms.

cURL

curl "https://api.vobiz.ai/api/v1/sms/opt-outs/%2B14155550123?channel=sms" \
  -H "X-Auth-ID: MA_XXXXXXXX" \
  -H "X-Auth-Token: YOUR_AUTH_TOKEN"

Response - 200 OK

{ "optedOut": true }

Call it before you add a number to a marketing list, or to explain to an agent why a send returned 422.

Remove an opt-out

Remove an opt-out deletes the entry for a number and channel. channel defaults to sms.

cURL

curl -X DELETE "https://api.vobiz.ai/api/v1/sms/opt-outs/%2B14155550123?channel=sms" \
  -H "X-Auth-ID: MA_XXXXXXXX" \
  -H "X-Auth-Token: YOUR_AUTH_TOKEN"

Response - 200 OK

{ "status": "ok" }

The call returns 200 whether or not an entry existed.

Remove an opt-out only when the contact has given you fresh, documented consent - a START reply, a signed form, a renewed subscription. Deleting an entry because a campaign needs more reach exposes you to complaints, carrier filtering and regulatory penalties, and can put your 10DLC or toll-free registration at risk.

What happens when you send to an opted-out number

Every recipient of Send a message is checked against the list for the message’s channel before routing:

A send where the only (or first) recipient is opted out creates no message and returns 422 {"error":"recipient has opted out: +14155550123"}.
In a multi-recipient send, the opted-out recipient is skipped and the others are sent; the call returns 202 Accepted with the first created message. See several recipients in one call.
An sms opt-out also blocks mms to that number, so a STOP reply to a text message suppresses picture messages too.
The check runs before the idempotency lookup, so replaying an earlier idempotencyKey to a number that has since opted out also returns 422.

Broadcasts

When you upload recipients to a broadcast, numbers with an sms opt-out are stored with status opted_out and counted in the upload result’s optedOut field. They are never sent, and they appear in the broadcast’s stats.optedOut and in the export. See Broadcasts.

Recommended practice

Include opt-out instructions (Reply STOP to opt out) in the first message of any marketing thread and in every broadcast template. US 10DLC and toll-free registration both expect this.
Reply to HELP with your brand name, a support contact and the STOP instruction. The help entries in the list show you who asked.
Mirror the list into your CRM by polling List opt-outs or by watching the message.received webhook event for keyword replies.
Record the consent that justifies every removal.

Before you go live

Messaging numbers

The numbers your opt-outs apply to.

India DLT

Consent and DLT rules for Indian recipients.

Broadcasts

Opted-out numbers are excluded from every broadcast.

Conversations

See keyword replies in the contact’s thread.

Compliance overview

Registration requirements that depend on opt-out handling.

Errors

The 422 opt-out response and other status codes.

Getting Started

API Reference

Guides

Vobiz Messaging Opt-outs

Keyword replies are recorded automatically

Add an opt-out manually

List opt-outs

Check one number

Remove an opt-out

What happens when you send to an opted-out number

Broadcasts

Recommended practice

Before you go live

Messaging numbers

India DLT

Broadcasts

Conversations

Compliance overview

Errors

​Keyword replies are recorded automatically

​Add an opt-out manually

​List opt-outs

​Check one number

​Remove an opt-out

​What happens when you send to an opted-out number

​Broadcasts

​Recommended practice

​Before you go live

Messaging numbers

India DLT

​Related

Broadcasts

Conversations

Compliance overview

Errors

Keyword replies are recorded automatically

Add an opt-out manually

List opt-outs

Check one number

Remove an opt-out

What happens when you send to an opted-out number

Broadcasts

Recommended practice

Before you go live

Related