Opt-outs

Numbers that must not receive your promotional messages. The list is applied before pricing, so you are never charged to message someone who opted out.

Ghana's NCA requires opt-out to work for promotional traffic. This list is per-organization: suppressing a number here does not affect other JKASMS customers.

What is and is not suppressed

Message type	Scope `PROMOTIONAL`	Scope `ALL`
`PROMOTIONAL`	Blocked	Blocked
`TRANSACTIONAL`	Delivered	Blocked
`OTP`	Delivered	Delivered

One-time codes are never suppressed, at any scope. Blocking a login code because someone once opted out of a marketing campaign would lock them out of their own account.

List opt-outs

GET/api/v1/suppressions

Query parameters

string

Matches against the phone number.

scope

string

PROMOTIONAL or ALL.

limit

integer

1–200. Defaults to 50.

cursor

string

The next_cursor from the previous page.

Response200

JSON

{
  "success": true,
  "data": [
    {
      "id": "cmuaxosro0001twq8d10e3wiz",
      "phone": "+233244123456",
      "scope": "PROMOTIONAL",
      "reason": "Replied STOP on old provider",
      "source": "api",
      "created_at": "2026-09-21T07:38:46.309Z"
    }
  ],
  "total": 1,
  "has_more": false,
  "next_cursor": null
}

Add opt-outs

POST/api/v1/suppressions

Parameters

phones

string[]required

Up to 5000 numbers in any format. Normalised with the same rules as send, so a number added as 0244… matches a send addressed to +233244….

scope

string

PROMOTIONAL (default) or ALL.

reason

string

Up to 200 characters, for your own records.

Shell

curl -X POST https://api.jkasms.com/api/v1/suppressions \
  -H "Authorization: Bearer $JKASMS_SECRET_KEY" \
  -H "X-JKASMS-Org-Id: $JKASMS_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "phones": ["0244123456", "+233201112222"],
    "scope": "PROMOTIONAL",
    "reason": "Replied STOP"
  }'

Response201

JSON

{
  "success": true,
  "data": {
    "added": 2,
    "already_suppressed": 0,
    "invalid": 0,
    "invalid_numbers": [],
    "duplicates_removed": 0
  }
}

Adding is idempotent. Re-posting a number that is already on the list counts under already_suppressed and is a success, not a conflict — re-uploading your opt-out list after adding ten names should not require diffing it first.

Remove an opt-out

DELETE/api/v1/suppressions/:phone

Keyed by phone number, URL-encoded, in any format. Removing an entry lets you market to that person again, so it is recorded in your audit log. A number that is not on the list returns 404.

Export

GET/api/v1/suppressions/export

Returns text/csv — useful when a regulator asks, or when moving to or from another provider.