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

# Vobiz Messaging API - Opt-outs

> Add, list, check and remove numbers on your Vobiz opt-out list by API, and learn how STOP, START and HELP replies and sends to opted-out numbers are handled.

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`](/docs/sms/api/opt-outs/create-opt-out) | Add a number to your opt-out list for a channel. |
| `GET` | [`/opt-outs`](/docs/sms/api/opt-outs/list-opt-outs) | List opt-out records, newest first. `limit` and `offset` are required. |
| `GET` | [`/opt-outs/{phoneNumber}`](/docs/sms/api/opt-outs/check-opt-out) | Check whether one number is blocked on a channel. |
| `DELETE` | [`/opt-outs/{phoneNumber}`](/docs/sms/api/opt-outs/delete-opt-out) | 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](/docs/sms/api/opt-outs/delete-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

```bash cURL theme={null}
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"}'
```

```json 201 Created theme={null}
{"status": "ok"}
```

```bash cURL theme={null}
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"
```

```json 200 OK theme={null}
{"optedOut": true}
```

## Related

* [Opt-outs guide](/docs/sms/opt-outs)
* [Compliance overview](/docs/sms/compliance/overview)
* [Broadcasts](/docs/sms/broadcasts)
* [Messages API](/docs/sms/api/messages)
* [Errors](/docs/sms/errors)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.