Blacklist
A message to a blacklisted number is created with status: "blocked" and errorCode: "blacklisted" and never reaches a phone. Campaigns skip these numbers, imports skip them, and Verify refuses them with 422 verify_recipient_blacklisted. A STOP reply adds the sender automatically; START removes that entry. See STOP and START.
The entry object
Section titled “The entry object”| Field | Type | Description |
|---|---|---|
id |
string | blk_… |
phone |
string | E.164. |
reason |
string or null | Your note. |
source |
string | manual, or opt_out when the recipient replied STOP. |
createdAt |
string |
List entries
Section titled “List entries”GET
/v1/blacklistblacklist:manageNewest first, paginated with limit and cursor.
curl https://api.smsfabric.com/v1/blacklist \ -H "X-Api-Key: $SMSFABRIC_API_KEY"{ "data": [ { "id": "blk_i3l6o9r2u5x8a1d4g7j0m3p6", "phone": "+201001234568", "reason": null, "source": "opt_out", "createdAt": "2026-11-18T19:04:11.000Z" }, { "id": "blk_j4m7p0s3v6y9b2e5h8k1n4q7", "phone": "+966501234567", "reason": "Asked by phone not to be contacted", "source": "manual", "createdAt": "2026-11-02T09:12:40.000Z" } ], "nextCursor": null}Add a number
Section titled “Add a number”POST
/v1/blacklistblacklist:manageReturns 201 with the entry. Supports Idempotency-Key. Audited as blacklist.added.
| Body field | Type | Required | Constraints |
|---|---|---|---|
phone |
string | Yes | E.164. |
reason |
string | No | Up to 500 characters. |
curl https://api.smsfabric.com/v1/blacklist \ -H "X-Api-Key: $SMSFABRIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{"phone": "+966501234567", "reason": "Asked by phone not to be contacted"}'| Error | When |
|---|---|
409 already_blacklisted |
The number is already on the list. |
400 validation_failed |
The number is not valid E.164. |
Remove a number
Section titled “Remove a number”DELETE
/v1/blacklist/:idblacklist:manageReturns 204. Audited as blacklist.removed. Messages already blocked stay blocked; new ones are sent.
curl -X DELETE https://api.smsfabric.com/v1/blacklist/blk_j4m7p0s3v6y9b2e5h8k1n4q7 \ -H "X-Api-Key: $SMSFABRIC_API_KEY"