Skip to content
Shortcut: /, ⌘K or Ctrl+K

Opt-outs and STOP replies

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

View as Markdown

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#

WhenWhat happens
A campaign launchesEvery recipient on the opt-out list is marked skipped with failureReason opted_out and counted once in skippedCount
A recipient is about to be sentA 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

Shell
# 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"

API Create opt outs 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#

cURL
curl "https://api.polymorfa.com/platform/optouts/settings" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
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.

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
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.

RuleValue
Keywords per listAt most 50
Keyword length1 to 32 characters after surrounding punctuation and whitespace are trimmed
optOutKeywordsAt least one keyword
Shared keywordsThe two lists must not share a keyword
StorageKeywords are stored in upper case
PropagationA 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#

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 before updating the preference. 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.

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
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:

Shell
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.

See also#