# Opt-outs and STOP replies

> Keep your team's suppression list, capture STOP and START replies, and mirror both in your system.

The opt-out list is your team's suppression list: numbers that campaigns must
not message. It is team-wide, so a number that opts out of one project's
campaign is suppressed in every project of that team.

Polymorfa enforces the list at two points and keeps it up to date from your
contacts' own replies.

## Where the list is enforced

| When | What happens |
| --- | --- |
| A campaign launches | Every recipient on the opt-out list is marked `skipped` with `failureReason` `opted_out` and counted once in `skippedCount` |
| A recipient is about to be sent | A number on the list is never claimed for sending, whatever its recipient status is |

Because the second check runs at send time, a number added to the list after a
campaign launched is still suppressed. Re-queuing a skipped recipient does not
send to a number that is on the list.

## Manage the list directly

**Console:**

Open **Campaigns**, then **Opt-outs**. The table shows each number, how it was
added (**Manual**, **STOP reply**, **API** or **Bulk import**), when and any
note.

- To add one number, select **Add opt-out**, enter it with an optional note
  and select **Add**.
- To add many, select **Import**, paste one number per line and select
  **Import opt-outs**. Duplicates are skipped.
- To remove a number, open its row actions, select **Remove opt-out** and
  confirm. Campaigns can message that number again.
- Select **Export** to download the list.

**API:**

```bash
# Add one number
curl -X POST "https://api.polymorfa.com/platform/optouts" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+14155550100" }'

# Read the list
curl "https://api.polymorfa.com/platform/optouts" \
  -H "Authorization: Bearer $POLYMORFA_KEY"

# Remove one number
curl -X DELETE "https://api.polymorfa.com/platform/optouts/%2B14155550100" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
```

`POST /platform/optouts/batch` takes a `phones` array and adds up to 1,000
numbers in one request. Reading needs a team key with `campaigns:read`;
every change needs `campaigns:manage`. Project tokens are refused on opt-out
routes.

## STOP and START replies

When keyword capture is on, a contact who replies `STOP` to one of your campaign
messages is added to the opt-out list, and a contact who replies `START` is
removed from it.

A reply changes the list only when all of the following hold:

- It is a direct text message, not a group message.
- The whole message matches a configured keyword. Matching ignores letter case
  and surrounding punctuation and whitespace, so `STOP`, `stop` and ` stop! `
  all match. `please stop` does not.
- The replying number received a campaign message from your team in the last
  30 days.

An opt-in keyword removes only an opt-out that a keyword reply created. An
opt-out you added by hand, by file or through the API is never removed by a
reply, so an explicit suppression stays in place.

Polymorfa compares the message body in memory and discards it. The body is never
stored, and the events below carry the keyword that matched, never the message.

## Configure the keywords

```bash cURL
curl "https://api.polymorfa.com/platform/optouts/settings" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
```

```typescript TypeScript
const settings = await platform.optOuts.getSettings();
console.log(settings.data.data.enabled, settings.data.data.optOutKeywords);
```

```json
{
  "data": {
    "enabled": true,
    "optOutKeywords": ["STOP", "STOPALL", "UNSUBSCRIBE", "CANCEL", "END", "QUIT",
                       "PARAR", "SAIR", "CANCELAR", "DESCADASTRAR", "BAJA"],
    "optInKeywords": ["START", "UNSTOP"],
    "updatedAt": null
  }
}
```

Those are the defaults. `updatedAt` is `null` until you save settings of your
own. `PUT` replaces all three fields at once: send every one of them, and send
nothing else, because an unrecognized field fails the request.

```bash cURL
curl -X PUT "https://api.polymorfa.com/platform/optouts/settings" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "optOutKeywords": ["STOP", "UNSUBSCRIBE", "PARAR"],
    "optInKeywords": ["START"]
  }'
```

```typescript TypeScript
await platform.optOuts.updateSettings({
  enabled: true,
  optOutKeywords: ["STOP", "UNSUBSCRIBE", "PARAR"],
  optInKeywords: ["START"],
});
```

*TypeScript:*

`updateSettings` also replaces all three fields. Opt-out methods need a team
key on the team client; project tokens are refused.

| Rule | Value |
| --- | --- |
| Keywords per list | At most 50 |
| Keyword length | 1 to 32 characters after surrounding punctuation and whitespace are trimmed |
| `optOutKeywords` | At least one keyword |
| Shared keywords | The two lists must not share a keyword |
| Storage | Keywords are stored in upper case |
| Propagation | A change applies to replies within 30 seconds |

Set `enabled` to `false` to stop reading replies for keywords. The opt-out list
itself keeps working: existing entries stay suppressed and the API still adds
and removes numbers.

Reading settings needs `campaigns:read`; changing them needs `campaigns:manage`.
Both require a team key. Keyword settings are changed through the API.

## Optional STOP confirmations

> **Note**
>
> **STOP confirmations require access.** They are off by default, including for
> teams that joined the beta. Reading the preference and turning it off remain
> available when access ends.

A confirmation is a short acknowledgement sent to a contact whose STOP reply
opted them out. It uses fixed text in English, Brazilian Portuguese or Spanish,
without links, media or promotional content.

Confirmations apply only to a new opt-out captured from a matching keyword
reply. Duplicate STOP messages, an existing suppression, and opt-outs added
manually or through imports do not generate acknowledgements. A later START
followed by a new STOP can create a new opt-out and acknowledgement.

The receiving connection must remain connected and eligible to send. An
acknowledgement is submitted within five minutes of the original reply, using
that same connection. Funding, provider restrictions, and sending safeguards
still apply. Standalone linked-device and Cloud API Numbers are supported;
Hybrid Link Numbers and test numbers do not send confirmations.

If acknowledgement submission fails or its outcome is unknown, suppression
stays recorded. An uncertain submission is never resent. The outcome counts
cover 30 days; **Provider accepted** does not confirm delivery.

**Console:**

A team owner or admin opens **Campaigns**, then **Settings**, turns on
confirmations under **STOP confirmations**, selects the language and saves.

**API:**

Use [Read confirmation settings](https://docs.polymorfa.com/api/opt-outs/get-stop-confirmation-settings)
before [updating the preference](https://docs.polymorfa.com/api/opt-outs/update-stop-confirmation-settings).
Send the returned `teamId` and `revision` with the chosen `enabled` and `locale`
values. A stale revision returns `409`; read again before deciding whether to
save another change. Reading requires `campaigns:read`, and changing the
preference requires `campaigns:manage` on a team key.

```bash cURL
curl -X PUT "https://api.polymorfa.com/platform/optouts/confirmation-settings" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"teamId":"019d0000-0000-7000-8000-000000000002","revision":0,"enabled":false,"locale":null}'
```

```typescript TypeScript
const current = await platform.optOuts.getConfirmationSettings();
const { teamId, revision } = current.data.data;

await platform.optOuts.updateConfirmationSettings({ teamId, revision, enabled: false, locale: null });
```

Replace the example team and revision with those returned by your settings
read. This example keeps acknowledgements disabled. Choose `en`, `pt-BR` or
`es` before enabling. Never retry an uncertain preference save automatically:
read the saved preference to learn its outcome.

*TypeScript:*

`optOuts.getConfirmationSettings`, `optOuts.updateConfirmationSettings` and
`optOuts.getConfirmationSummary` are on the team client from SDK version
`0.1.0-dev.20261005233122`. They keep the API envelope, so read the result at
`response.data.data`. With an older package, call the same routes with
`platform.raw.request`. A package upgrade does not enable acknowledgements or
grant beta access.

**CLI:**

When your installed CLI includes STOP confirmation commands, read the team and
revision, then save an explicit choice:

```bash
polymorfa optout confirmations view
polymorfa optout confirmations update \
  --team-id 019d0000-0000-7000-8000-000000000002 \
  --revision 0 --enabled --locale pt-BR
polymorfa optout confirmations summary --json
```

Use the `teamId` and `revision` from your own `view` result. To turn
acknowledgements off, run `update` with `--no-enabled` and omit `--locale`.
The CLI sends one update request; after an error or timeout, read the setting
before making another change.

## Webhook events

Subscribe to `contact.opted_out` and `contact.opted_in` to mirror keyword
changes in your own system.

```json
{
  "id": "01995b51-bc80-7000-8000-000000000001",
  "session": "sales-1",
  "timestamp": "2026-09-20T10:15:30.000Z",
  "event": "contact.opted_out",
  "payload": {
    "phone": "+14155550100",
    "source": "stop-keyword",
    "keyword": "STOP",
    "session": "sales-1",
    "projectId": "0b0b6a36-33d2-4f1e-9a10-2f7a1f0d55c1"
  }
}
```

`source` is always `stop-keyword`: these two events report keyword replies, not
changes you make through the API or the Console. `keyword` is the configured
keyword that matched, in upper case. See
[Event types](https://docs.polymorfa.com/api/events#types).

## See also

- [How campaigns work](https://docs.polymorfa.com/campaigns/how-campaigns-work)
- [Campaign safety checks](https://docs.polymorfa.com/campaigns/safety-checks)
- [Opt-out API reference](https://docs.polymorfa.com/api/opt-outs/list-opt-outs)
