Table of Contents

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

Why should you blacklist numbers?

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

One way to ensure particular recipients won’t be included in any upcoming campaigns (single or bulk SMS) is to exclude them in the SMSAPI Customer Portal manually. Simply add selected phone numbers to the blacklist.

It may also be that your CRM already has a consent module, and you don’t want to double your efforts. In that case, you can integrate it with SMSAPI using Blacklist API. This post will teach you how to keep your blacklist software in sync.

SMS API blacklist prerequisites

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

For the purpose of this article, I will 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.

The Blacklist API is a RESTfull API. Find its OpenAPI specification-based is the documentation. That’s JSON format-based API, so all requests and responses (with minor deviations) are expected to be in that format. Blacklist API responds with meaningful HTTP status codes on which you can rely to determine your request results, including errors.

Managing blacklist

Let’s go through the most common actions you can perform on your blacklist: listing, adding data (numbers) and deleting it all together.

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. Let’s look up the blacklist again:

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

We tried to send SMS and got an error. That’s good. This error is described: ‘The number is blacklisted for this user’. SMS delivery API error code descriptions are listed in the documentation.

While adding phone numbers, you may encounter some client-side errors (yes, your errors). Those errors are easily recognizable with 4xx HTTP status codes. Check out the blacklist API error response body to get an additional hint about what’s wrong. Before we add a phone number to the blacklist, it is proceeded and validated against a set of rules. Firstly, a phone number must look like a phone number. Next, it must exist on the SMSAPI numbering plan.

Deleting a phone number from blacklist

What if you don’t want to block blacklisted phone numbers 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 the response to the file (pay attention to the `Accept` header):

Moreover, you can use limit/offset to paginate your blacklist or chunk your blacklist export file into smaller ones. Blacklist query API ships with phone numbers search engine as well. Pass the `q` parameter with a phone number part as a value to use it. In response, you will see all blacklisted phone numbers that contain that sought part.

You can also import a blacklist from a file:

In case of very big blacklists, you may encounter timeout issues, SMSAPI gateway or your server side. To deal with that, you can order exports to be asynchronous. To do that, add the `x-async` header while exporting the blacklist to the file.

Summary

You were shown how to manage your blacklist using our API in this short article. 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!