---
title: "Opt-outs"
description: "How opt-outs are recorded and enforced, and how to use separate opt-out lists."
---

> Documentation Index
> Fetch the complete documentation index at: https://dev.touchsms.com.au/llms.txt
> Use this file to discover all available pages before exploring further.

# Opt-outs

When someone opts out, we stop sending them messages. Opt-outs are recorded automatically when a recipient replies with an opt-out keyword such as `STOP` or uses an opt-out link, and you can add or remove them yourself through the web interface or the API.

## How sending checks opt-outs

Every message you [send](/guides/sending-messages/) is checked against an opt-out list. If the recipient is on it, the message is rejected with `RECIPIENT_OPTED_OUT` and isn't sent or charged.

- By default, messages are checked against your account's **default opt-out list**.
- To check against a different list, pass `opt_out_list_id` or `opt_out_list_name` at the root of the send request. The message is then checked against **that list instead of the default list**.

```json
{
  "opt_out_list_name": "Marketing Opt-Outs",
  "messages": [
    { "from": "+61412345678", "to": "+61412345679", "body": "20% off this weekend. Reply STOP to opt out." }
  ]
}
```

If the list doesn't belong to your account, the request fails with a `422`.

## Opt-out lists

Every account has a default opt-out list, created automatically. Add more lists to keep opt-outs separate, for example one per brand or per type of message, so someone who opts out of marketing can still get appointment reminders.

| Task | Endpoint |
|---|---|
| List your opt-out lists | [List opt-out lists](/api/optout-lists/list/) |
| Get one list and its opt-out count | [Get opt-out list](/api/optout-lists/get/) |
| List the opt-outs on one list | [List opt-outs on a list](/api/optout-lists/list-optouts/) |

Opt-out lists are listed with the default list first, then alphabetically. Lists are created in the web interface, or automatically when you add an opt-out with an `opt_out_list_name` that doesn't exist yet.

## Manage opt-outs

| Task | Endpoint |
|---|---|
| List or search opt-outs across all lists | [List opt-outs](/api/optouts/list/) |
| Get one opt-out | [Get opt-out](/api/optouts/get/) |
| Add a number | [Create opt-out](/api/optouts/create/) |
| Remove a number | [Delete opt-out](/api/optouts/delete/) |

When you add an opt-out:

- Pass `opt_out_list_id` or `opt_out_list_name` to choose the list. Without either, the number goes on your default list. You can't pass both.
- With `opt_out_list_name`, the list is created if it doesn't exist.
- If the number is already opted out on that list, no duplicate is created.

To remove an opt-out, search for the number with [List opt-outs](/api/optouts/list/) (`search` matches part or all of a number), then delete it by `id`.

> **Caution**
>
> Only remove an opt-out when the recipient has clearly asked to receive messages again. Messaging people who have opted out can breach anti-spam law.

## Get notified of new opt-outs

Subscribe to the [`optout_created` webhook](/guides/webhooks/#optout_created) to sync opt-outs into your own system as they happen. It fires for opt-outs from replies, links, the web interface and the API, but not for imported opt-outs.

Source: https://dev.touchsms.com.au/guides/opt-outs/index.mdx