Opt-outs

GET/POST/DELETE /api/opt-outs - Manage your STOP list; STOP/START handled automatically.

Overview

Every account has an opt-out (STOP) list. Recipients on it are automatically suppressed from single sends, bulk sends and OTP - you never message someone who unsubscribed. When a recipient replies STOP (or UNSUBSCRIBE, CANCEL, END, QUIT, OPTOUT, ...) they are added automatically; replying START (or UNSTOP, SUBSCRIBE, RESUME, OPTIN) removes them. Use this API to inspect and manage the list yourself.

Authentication

Authorization: Bearer esms_live_your_api_key

List opt-outs

GET https://sms.esmsafrica.io/api/opt-outs

Parameter	Type	Description
`limit`	integer	Max rows, up to `1000` (default `200`).

Response

{
  "opt_outs": [
    {
      "phone": "+254712345678",
      "source": "sms",
      "keyword": "STOP",
      "created_at": "2026-08-14T12:40:00+00:00"
    }
  ]
}

source is sms (recipient texted STOP) or api (added via this endpoint).

Add an opt-out

POST https://sms.esmsafrica.io/api/opt-outs

{ "phone": "+254712345678" }

Returns 201 with { "phone": "+254712345678", "opted_out": true }. Idempotent - adding an existing number succeeds without duplicating it. A malformed number returns 400.

Remove an opt-out

DELETE https://sms.esmsafrica.io/api/opt-outs/{phone}

Returns { "phone": "+254712345678", "opted_out": false }. The number can be messaged again after removal.

Example

# Add
curl -X POST https://sms.esmsafrica.io/api/opt-outs \
  -H "Authorization: Bearer esms_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+254712345678" }'

# Remove
curl -X DELETE https://sms.esmsafrica.io/api/opt-outs/+254712345678 \
  -H "Authorization: Bearer esms_live_your_api_key"