Vobiz Messaging API - Opt-outs

An opt-out is a phone number that must not receive messages from your account on a channel. Vobiz checks every send and every broadcast recipient against your opt-out list before anything leaves the platform. You use the Opt-outs endpoints to add numbers, check them before a send, review the list, and remove a number once a contact has given consent again.

The opt-out object

Field	Type	Description
`id`	string (UUID)	Unique identifier of the opt-out record.
`accountId`	string	Your Vobiz account ID, for example `MA_XXXXXXXX`.
`phoneNumber`	string	The blocked number in E.164 format.
`channel`	string	`sms`, `mms` or `rcs`. An `sms` entry also blocks `mms`.
`reason`	string	`stop`, `start` or `help` from a keyword reply; `manual` or your own text when created by API or console.
`source`	string	`inbound` for a keyword reply, `manual` for the API or console.
`syncedToProvider`	boolean	`true` when the block has also been applied on the upstream network.
`createdAt`	string (ISO 8601)	When the number was added to the list.

Endpoints

Method	Endpoint	What it does
`POST`	`/opt-outs`	Add a number to your opt-out list for a channel.
`GET`	`/opt-outs`	List opt-out records, newest first. `limit` and `offset` are required.
`GET`	`/opt-outs/{phoneNumber}`	Check whether one number is blocked on a channel.
`DELETE`	`/opt-outs/{phoneNumber}`	Remove a number from the list for a channel.

All paths are relative to https://api.vobiz.ai/api/v1/sms. Every request carries your X-Auth-ID and X-Auth-Token headers. In path parameters, URL-encode the + of the number as %2B, for example /opt-outs/%2B14155550123.

Keyword replies

When a contact replies to one of your numbers with a standard keyword, Vobiz records an opt-out for that number and channel with source: "inbound". The reply is lower-cased, trimmed and stripped of trailing punctuation before matching.

Reply	`reason`
`STOP`, `UNSUBSCRIBE`, `CANCEL`, `END`	`stop`
`START`, `SUBSCRIBE`, `UNSTOP`	`start`
`HELP`, `INFO`	`help`

When a contact replies START, confirm their consent and then remove the entry with Delete an opt-out.

Channels and defaults

Every opt-out applies to one channel. channel defaults to sms on create, check and delete. An sms opt-out also blocks mms to the same number. Create a separate entry for rcs. Creating the same number and channel again updates reason instead of adding a second record, and deleting a number that is not on the list still returns 200.

What happens on a send

POST /messages to an opted-out number on a blocked channel returns 422 with {"error": "recipient has opted out: +14155550123"} and records nothing for that recipient. With several recipients, the others are still sent and the response is 202. Broadcast recipients on the list are marked opted_out and skipped.

Pagination

GET /opt-outs returns a bare JSON array, newest first. Pass both limit and offset on every call. A page with no records, or a request without limit, returns null. Increase offset by limit until a page returns fewer items than limit.

Example

cURL

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": "customer request"}'

201 Created

{"status": "ok"}

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"

200 OK

{"optedOut": true}

Getting Started

API Reference

Guides

Vobiz Messaging API - Opt-outs

The opt-out object

Endpoints

Keyword replies

Channels and defaults

What happens on a send

Example

​The opt-out object

​Endpoints

​Keyword replies

​Channels and defaults

​What happens on a send

​Pagination

​Example

​Related

The opt-out object

Endpoints

Keyword replies

Channels and defaults

What happens on a send

Pagination

Example

Related