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

Opt-outs

View as Markdown

The opt-out settings object

Attributes

  • enabledbooleanrequired

    Whether keyword replies change the opt-out list.

  • optOutKeywordsarray of stringrequireditems1–50item length1–32

    Opt out keywords associated with this management opt out setting.

  • optInKeywordsarray of stringrequiredmax items50item length1–32

    Opt in keywords associated with this management opt out setting.

  • updatedAtintegerrequirednullableformatint64

    Unix time in milliseconds of the last change; null while the defaults apply.

The opt-out settings object
{
  "enabled": true,
  "optOutKeywords": [
    "string"
  ],
  "optInKeywords": [
    "string"
  ],
  "updatedAt": 0
}

Create opt out

POST/platform/optoutsPlatform API
Base URL
https://api.polymorfa.com
Required permission
campaigns:manage

Public Management API. Team keys require campaigns:manage. Project tokens are not accepted.

Body

Responses

  • 200Success
    • dataanyrequired

      Operation result.

    Show 3 headers
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
POST /platform/optoutscURL
Not available with the Test key. Use a team key or project token.
curl -X POST "https://api.polymorfa.com/platform/optouts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": null
}

Create opt outs

POST/platform/optouts/batchPlatform API
Base URL
https://api.polymorfa.com
Required permission
campaigns:manage

Public Management API. Team keys require campaigns:manage. Project tokens are not accepted.

Body

Responses

  • 200Success
    • dataanyrequired

      Operation result.

    Show 3 headers
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
POST /platform/optouts/batchcURL
Not available with the Test key. Use a team key or project token.
curl -X POST "https://api.polymorfa.com/platform/optouts/batch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": null
}

List opt outs

GET/platform/optoutsPlatform API
Base URL
https://api.polymorfa.com
Required permission
campaigns:read

Public Management API. Team keys require campaigns:read. Project tokens are not accepted.

Responses

  • 200Success
    • dataanyrequired

      Operation result.

    Show 3 headers
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
GET /platform/optoutscURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/optouts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "data": null
}

Get opt out settings

GET/platform/optouts/settingsPlatform API
Base URL
https://api.polymorfa.com
Required permission
campaigns:read

Returns whether keyword opt-out capture is enabled for the team and the opt-out and opt-in keyword lists. A team that never saved settings receives the defaults: enabled, opt-out keywords STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT, PARAR, SAIR, CANCELAR, DESCADASTRAR, BAJA, and opt-in keywords START, UNSTOP. updatedAt is null while the defaults apply.

Team keys require campaigns:read. Project tokens are not accepted.

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 4 child fields
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
GET /platform/optouts/settingscURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/optouts/settings" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "data": {
    "enabled": true,
    "optOutKeywords": [
      "string"
    ],
    "optInKeywords": [
      "string"
    ],
    "updatedAt": 0
  }
}

Get stop confirmation settings

GET/platform/optouts/confirmation-settingsPlatform API
Base URL
https://api.polymorfa.com
Required permission
campaigns:read

Returns the team's optional acknowledgement preference. Confirmations are disabled by default. A locale is explicitly selected from English, Brazilian Portuguese or Spanish; the response includes the reviewed acknowledgement text. Reads remain available after beta withdrawal.

Team keys require campaigns:read. Project tokens are not accepted.

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 7 child fields
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
GET /platform/optouts/confirmation-settingscURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/optouts/confirmation-settings" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "data": {
    "teamId": "00000000-0000-4000-8000-000000000000",
    "enabled": true,
    "locale": "en",
    "revision": 0,
    "textRevision": 1,
    "acknowledgement": "string",
    "updatedAt": 0
  }
}

Get stop confirmation summary

GET/platform/optouts/confirmation-summaryPlatform API
Base URL
https://api.polymorfa.com
Required permission
campaigns:read

Returns aggregate acknowledgement outcomes from the last 30 days, without recipient phones or message content. Disabled is the preference state, queued is waiting, admitted may have been submitted, completed means the provider accepted the send rather than delivered it, failed is a proven skip or rejection, and unknown means the send outcome could not be established. All outcomes preserve the opt-out.

Team keys require campaigns:read. Project tokens are not accepted.

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 2 child fields
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
GET /platform/optouts/confirmation-summarycURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/optouts/confirmation-summary" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "data": {
    "enabled": true,
    "counts": {
      "queued": 0,
      "admitted": 0,
      "completed": 0,
      "failed": 0,
      "unknown": 0
    }
  }
}

Update opt out settings

PUT/platform/optouts/settingsPlatform API
Base URL
https://api.polymorfa.com
Required permission
campaigns:manage

Replaces the team's keyword opt-out settings. When enabled, a direct text reply whose whole body matches an opt-out keyword, from a number that received a campaign message from the team in the last 30 days, adds that number to the opt-out list with source stop-keyword and emits contact.opted_out. Matching ignores letter case and surrounding punctuation and whitespace. An opt-in keyword removes only an opt-out created this way and emits contact.opted_in; opt-outs added manually, by file or through the API are never removed by a reply. Each list holds at most 50 keywords of 1 to 32 characters, the opt-out list needs at least one keyword, and the two lists must not share a keyword. Keywords are stored in upper case. Changes apply to replies within 30 seconds.

Team keys require campaigns:manage. Project tokens are not accepted.

Body

  • enabledbooleanrequired

    Whether this feature is enabled.

  • optOutKeywordsarray of stringrequireditems1–50item length1–32

    Opt out keywords associated with this management update opt out settings input.

  • optInKeywordsarray of stringrequiredmax items50item length1–32

    Opt in keywords associated with this management update opt out settings input.

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 4 child fields
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
PUT /platform/optouts/settingscURL
Not available with the Test key. Use a team key or project token.
curl -X PUT "https://api.polymorfa.com/platform/optouts/settings" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "enabled": true,
  "optOutKeywords": [
    "string"
  ],
  "optInKeywords": [
    "string"
  ]
}'
Response
{
  "data": {
    "enabled": true,
    "optOutKeywords": [
      "string"
    ],
    "optInKeywords": [
      "string"
    ],
    "updatedAt": 0
  }
}

Update stop confirmation settings

PUT/platform/optouts/confirmation-settingsPlatform API
Base URL
https://api.polymorfa.com
Required permission
campaigns:manage

Replaces the team's preference using the observed revision. Enabling requires STOP confirmations beta access and a selected locale. A team owner or admin can also change it in the console. A new STOP opt-out queues at most one plain acknowledgement from the receiving connection; manual opt-outs, repeated STOP while suppressed and START produce none. A confirmation cannot undo suppression. Disabling remains available after beta withdrawal and cancels queued acknowledgements. A changed revision returns 409. Unknown send outcomes are never resent with a new operation identity.

Team keys require campaigns:manage. Project tokens are not accepted.

Body

  • teamIdstring (uuid)required

    The teamId returned by the settings read. Must match the authenticated team.

  • enabledbooleanrequired

    Whether this feature is enabled.

  • localestringrequirednullable

    Required when enabled. Never inferred from a phone number.

    Allowed valuesenpt-BRes
  • revisionintegerrequiredrange0–2147483646

    Specifies revision for this management update stop confirmation settings input.

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 7 child fields
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
  • 409The request conflicts with the resource's current state.
PUT /platform/optouts/confirmation-settingscURL
Not available with the Test key. Use a team key or project token.
curl -X PUT "https://api.polymorfa.com/platform/optouts/confirmation-settings" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "teamId": "00000000-0000-4000-8000-000000000000",
  "enabled": true,
  "locale": "en",
  "revision": 0
}'
Response
{
  "data": {
    "teamId": "00000000-0000-4000-8000-000000000000",
    "enabled": true,
    "locale": "en",
    "revision": 0,
    "textRevision": 1,
    "acknowledgement": "string",
    "updatedAt": 0
  }
}

Delete opt out

DELETE/platform/optouts/{phone}Platform API
Base URL
https://api.polymorfa.com
Required permission
campaigns:manage

Public Management API. Team keys require campaigns:manage. Project tokens are not accepted.

Path parameters

  • phonestringrequired

    Phone number in international format.

Responses

  • 200Success
    • dataanyrequired

      Operation result.

    Show 3 headers
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
DELETE /platform/optouts/{phone}cURL
Not available with the Test key. Use a team key or project token.
curl -X DELETE "https://api.polymorfa.com/platform/optouts/<phone>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "data": null
}