Skip to main content
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

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

POST /platform/optouts/batch takes a phones array and adds up to 1,000 numbers in one request. Reading needs a team API 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

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

​
Webhook events

Subscribe to contact.opted_out and contact.opted_in to mirror keyword changes in your own system.
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 Webhooks.