Opt-outs | MessagePort Developers

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

{
  "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
Get one list and its opt-out count	Get opt-out list
List the opt-outs on one list	List opt-outs on a list

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
Get one opt-out	Get opt-out
Add a number	Create opt-out
Remove a number	Delete opt-out

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 (search matches part or all of a number), then delete it by id.

Get notified of new opt-outs

Subscribe to the optout_created webhook 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.