Tags: English

How to create and manage your blacklist using API

15 January, 2020
Reading time: 2 min 58 sec
SMSAPI Blacklist API

So, you want to easily exclude SMS receivers from your upcoming campaigns? No matter the reason: GDPR, subscription cancellation, database maintenance, there’s a solution – our new Blacklist API.

It may happen that, occasionally, your customers are unhappy receiving your SMS messages. And in the times of data protection regulations and e-privacy changes, no one wants to mess with an unhappy customer.

To make sure they won’t be included in any of the upcoming campaigns, no matter if sent via single or bulk dispatch, you can log in to SMSAPI Customer Portal and add a selected phone number to the blacklist.

It may also be, that your CRM already has consents module, and you don’t want to double your efforts. In that case, you can integrate it with SMSAPI using Blacklist API. In this post, you will learn how.


Firstly, to use our Blacklist API  you must obtain an access token. You can easily get it in SMSAPI Customer Portal. When generating a new token make sure to check the blacklist scope. If you would like to connect to API as subuser, check the user blacklist settings. Each subuser can have his or her own blacklist or a shared one.

For the purpose of this article, I will use httpie – a command-line HTTP client. To test it, you can use any client – cURL might be your first-choice tool. For integration purposes, you can check one of our programming language-specified clients.

Managing blacklist

Listing blacklist

As the API user, you have access to one blacklist. You can store an unlimited amount of phone numbers there. Those phone numbers may be locked forever or for a limited time (with an expiration date defined). Let’s start by checking your blacklist:

We sent GET request to blacklist/phone_numbers endpoint. As you can see blacklist is empty.

Adding a phone number to blacklist

You can continue adding a phone number to our blacklist:

We sent POST request to the mentioned endpoint with the phone_number field within. In response, we received created blacklist entry details. You can now refer to a created blacklist entry using a given id. Let’s add another phone number but this time with an expiration date defined:

In this example response, we received another id and this time expire_at field is filled. Lets lookup blacklist again:

The collection is no longer empty. It has all the phone numbers we’ve added previously. You can check if blacklist works:

This error is described: ‘The number is blacklisted for this user’.

Deleting a phone number from blacklist

What if you don’t want to block blacklisted phone number any longer? Let’s remove it by its id:

We’ve deleted a phone number from the blacklist referring to it by its id. After that, the selected phone number will successfully receive SMS messages.

You can also delete the whole blacklist if you wish to, but remember – this operation is irreversible:

Exporting/importing a blacklist

The listed blacklist response is in JSON format by default. Additionally, you can request it to be in .CSV format and then redirect response to file:

You can also import blacklist from a file:


In this short article, you were shown how to manage your blacklist using our API. You can easily list, import and export the whole blacklist. You can add a phone number to it without any effort. Finally, you can delete a given phone number or entire blacklist if you wish to. I hope it helps!