SmsAddBlacklistPhone¶

POST sms/blacklist

Adds a number to the do-not-message list of the brand. The check runs in SmsSendMessage before the provider is contacted, so a blocked number costs nothing.

source is what makes the list auditable: a regulator entry, a manual block and an OPT_OUT are legally different things, and only the last one is limited to marketing.

Access Control¶

Allowed roles: admin, leader, manager. The entry belongs to the brand of the caller.

Request¶

RESTTCPSDK

POST https://{broker_domain}/sms/blacklist

{
  "phone": "+380 95 000 00 00",
  "source": "OPT_OUT",
  "reason": "Recipient replied STOP"
}

{
  "command": "SmsAddBlacklistPhone",
  "extID": "1",
  "data": {
    "phone": "+380 95 000 00 00",
    "source": "OPT_OUT",
    "reason": "Recipient replied STOP"
  }
}

const res = await platform.SmsAddBlacklistPhone({
  phone: "+380 95 000 00 00",
  source: "OPT_OUT",
  reason: "Recipient replied STOP"
});

Request Data¶

Field	Type	Required	Description
`phone`	string	Yes	Number in any human format; stored as digits only
`source`	enum	No	Where the block came from: `MANUAL`, `IMPORT`, `REGULATOR`, `OPT_OUT`, `SYSTEM`. Default `MANUAL`
`reason`	string	No	Free-form explanation, up to 512 characters
`expiresAt`	string	No	`YYYY-MM-DD HH:mm:ss`. Empty means the block never expires

Behavior¶

The number is stored as digits without separators, exactly as it is normalized at send time — otherwise +38 095 … and 38095… would be two entries and only one of them would block.
OPT_OUT blocks MARKETING only: unsubscribing from promotions is not a refusal to receive login codes, and treating it as one locks customers out of their accounts.
Blacklisting an already listed number updates the existing entry instead of creating a second one.
Inbound STOP replies handled by the module add entries here automatically with source: "OPT_OUT".

Response Data¶

The entry is returned flat. created: false means an existing entry was updated, restored: true that a previously removed entry came back.

{
  "id": 31,
  "brand": "default",
  "phone": "380950000000",
  "countryCode": "380",
  "countryIso": "UA",
  "source": "OPT_OUT",
  "reason": "Recipient replied STOP",
  "expiresAt": null,
  "createdAt": "2026-08-24 13:44:02",
  "created": true,
  "restored": false
}

Errors¶

Code	Error	Description
`400`	`VALIDATION_ERROR`	Number is too short to be a phone number
`500`	`INTERNAL_ERROR`	Storage error