Blacklist

Your team's opt-out list. Numbers on it are skipped by campaigns that set skip_blacklisted — keep it in sync with your own unsubscribe flows.

Endpoints live under /api/v1/ with a scoped mbs_ token or JWT. An entry can opt a number out of one sender (set sender_name) or out of everything your team sends (omit it).

Add a number

POST/api/v1/blacklist

Parameters

Field	Type	Required	Description
msisdn	string	Yes	The phone number, any accepted format (07…, 2547…, +2547…).
sender_name	string	No	Restrict the opt-out to this sender ID only. Omit for a global opt-out across all your senders.
reason	string	No	Free-text note — e.g. "replied STOP", "complained via support".

curl -X POST https://api.mobilesasa.com/api/v1/blacklist \
  -H "Authorization: Bearer $MOBILESASA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "msisdn": "0712345678",
    "sender_name": "DUKAPAY",
    "reason": "replied STOP"
  }'

View the list

GET/api/v1/blacklist

curl "https://api.mobilesasa.com/api/v1/blacklist?page=1&page_size=50" \
  -H "Authorization: Bearer $MOBILESASA_TOKEN"

Response — 200

{
  "success": true,
  "data": [
    {
      "uuid": "e7a21c04-…",
      "msisdn": "254712345678",
      "sender_name": "DUKAPAY",
      "reason": "replied STOP",
      "created_at": "2026-07-11T08:12:44Z"
    }
  ],
  "meta": { "page": 1, "page_size": 50, "total": 1 }
}

Remove an entry

DELETE/api/v1/blacklist/{uuid}

Removing an entry re-enables sends to that number. Use it when a customer opts back in.

curl -X DELETE "https://api.mobilesasa.com/api/v1/blacklist/e7a21c04-…" \
  -H "Authorization: Bearer $MOBILESASA_TOKEN"

Blacklist straight from a message

POST/api/v1/messages/{uuid}/blacklist

If you're looking at a sent message (say, one a customer complained about), this shortcut blacklists its recipient against that message's sender in one call — no need to re-derive the msisdn.

Honour STOP replies automatically

If you receive inbound traffic on a shortcode, watch for STOP-style keywords on your inbound webhook and add the sender to the blacklist immediately. Regulators take opt-out latency seriously.