Skip to content
/
Opt-Outs
Last updated

Opt-outs (Global Messaging Suppression)

Opt-outs allow you to prevent messages being sent to recipients who have unsubscribed or should no longer be contacted.

If a recipient is opted out, InstaMessage will block outbound messaging across all channels - SMS, WhatsApp, Messenger and RCS.

Important: Current opt-out behaviour

Opt-outs are currently global.

This means:

  • If a recipient opts out of any message, they are opted out of all channels:
    • SMS
    • WhatsApp
    • Messenger
    • RCS
  • We do not currently differentiate between:
    • Marketing vs transactional messages
    • Channel-specific opt-outs

If a number is opted out, no messages of any type will be sent to that recipient.

Support for marketing-only opt-outs and transactional overrides is planned for a future release.

What is an opt-out?

An opt-out is a record that a recipient should not receive messages from your account.

Opt-outs may be created when:

  • A recipient unsubscribes via a link (if configured)
  • You import a suppression list from another system
  • You explicitly add a recipient via the API

How opt-outs are enforced

Before sending a message, InstaMessage checks the recipient against the opt-out list.

  • If the recipient is opted out, the Send Message request will be rejected
  • The message will not be sent on any channel
  • An error response will be returned

This ensures compliance across all messaging channels.

Endpoints

List opt-outs

Retrieve all opt-outs for your account.

You can use the since parameter to fetch only newly added opt-outs.

GET https://api.instamessage.co.uk/v1/opt-outs

Query parameters

ParameterTypeRequiredDescription
sinceintegerNoUNIX timestamp (seconds). If provided, only opt-outs added since this time are returned.
limitintegerNoNumber of records to return (default 100, max 1000).
cursorstringNoPagination cursor from a previous response.

Create opt-outs

Add one or more phone numbers to your global opt-out list.

POST https://api.instamessage.co.uk/v1/opt-outs

Request body

FieldTypeRequiredDescription
entriesarray[string]YesList of phone numbers in E.164 format (e.g. +447123456789).

Remove an opt-out (re-subscribe)

Remove a phone number from the opt-out list.

DELETE https://api.instamessage.co.uk/v1/opt-outs/{phone}

Path parameters

ParameterTypeRequiredDescription
phonestringYesPhone number in E.164 format (URL-encoded).

Authentication

All opt-out endpoints require authentication using your API key:

Authorization: Bearer YOUR_API_KEY

Examples

List opt-outs

curl -X GET "https://api.instamessage.co.uk/v1/opt-outs?since=1733337600&limit=100" \
  -H "Authorization: Bearer $IM_API_KEY"

Create opt-outs (bulk)

curl -X POST "https://api.instamessage.co.uk/v1/opt-outs" \
  -H "Authorization: Bearer $IM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entries": ["+447123456789", "+447987654321"],
    "reason": "import"
  }'

Responses

List opt-outs response

{
  "data": [
    {
      "phone": "+447123456789",
      "created_at": "2025-12-12T10:15:30Z",
      "reason": "stop_keyword"
    }
  ],
  "next_cursor": null
}

Create opt-outs response

{
  "created": 2,
  "skipped": 0
}

Common errors

ErrorDescription
invalid_phonePhone number is not valid E.164 format
too_many_entriesToo many opt-outs in a single request
unauthorizedAPI key missing or invalid
opted_outRecipient is opted out and messaging is blocked

Relationship to webhooks

If you receive opt-out events via webhook, remember:

  • Webhooks are delivered on a best-effort basis
  • Events are not retried if your endpoint is unavailable

You should treat this Opt-outs API as the source of truth for compliance checks.

Next steps

Inbound messages