{"id":2783,"date":"2022-11-23T12:22:02","date_gmt":"2022-11-23T11:22:02","guid":{"rendered":"https:\/\/www.smsapi.com\/blog\/?p=2783"},"modified":"2023-02-07T16:01:22","modified_gmt":"2023-02-07T15:01:22","slug":"how-to-create-manage-blacklist-using-api","status":"publish","type":"post","link":"https:\/\/www.smsapi.com\/blog\/how-to-create-manage-blacklist-using-api\/","title":{"rendered":"How to create and manage your blacklist API"},"content":{"rendered":"\n<p><strong><strong>So, do you want to exclude SMS receivers from your upcoming campaigns easily? No matter the reason: GDPR, subscription cancellation, or database maintenance, there&#8217;s a solution \u2013 our new Blacklist API.<\/strong><\/strong><\/p>\n\n\n\n<!--more-->\n\n\n\n<figure class=\"wp-block-embed is-type-video is-provider-youtube wp-block-embed-youtube wp-embed-aspect-16-9 wp-has-aspect-ratio\"><div class=\"wp-block-embed__wrapper\">\n<iframe loading=\"lazy\" title=\"Promo: How to create and manage your blacklist using API\" width=\"640\" height=\"360\" src=\"https:\/\/www.youtube.com\/embed\/Bv4HsmBCZtk?feature=oembed\" frameborder=\"0\" allow=\"accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share\" referrerpolicy=\"strict-origin-when-cross-origin\" allowfullscreen><\/iframe>\n<\/div><\/figure>\n\n\n\n<h2 class=\"wp-block-heading\">Why should you blacklist numbers?<\/h2>\n\n\n\n<p>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.<\/p>\n\n\n\n<p>One way to ensure particular recipients won&#8217;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.<\/p>\n\n\n\n<p>It may also be that <a rel=\"noreferrer noopener\" href=\"https:\/\/blog.salesflare.com\/compare-salesforce-zoho-hubspot-pipedrive\" target=\"_blank\">your CRM<\/a> already has a consent module, and you don&#8217;t want to double your efforts. In that case, you can <a href=\"https:\/\/www.smsapi.com\/blog\/sms-api-integration-checklist\/\" target=\"_blank\" rel=\"noreferrer noopener\">integrate it with SMSAPI<\/a> using Blacklist API. This post will teach you how to keep your blacklist software in sync.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">SMS API blacklist prerequisites<\/h2>\n\n\n\n<p>Firstly, to use our <a target=\"_blank\" href=\"https:\/\/smsapi.com\/rest#\/blacklist\" rel=\"noopener\">Blacklist API<\/a>, 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.<\/p>\n\n\n\n<p>For the purpose of this article, I will <a target=\"_blank\" rel=\"noreferrer noopener nofollow\" href=\"https:\/\/httpie.org\/\">httpie<\/a> \u2013 a command-line HTTP client. To test it, you can use any client \u2013 <a target=\"_blank\" rel=\"noreferrer noopener nofollow\" href=\"https:\/\/en.wikipedia.org\/wiki\/CURL\">cURL<\/a> might be your first-choice tool. For integration purposes, you can check one of our <a target=\"_blank\" rel=\"noreferrer noopener nofollow\" href=\"https:\/\/github.com\/smsapi\">programming language-specified clients<\/a>.<\/p>\n\n\n\n<p>The Blacklist API is a RESTfull API. Find its OpenAPI specification-based is the <a target=\"_blank\" href=\"https:\/\/www.smsapi.com\/rest\/#\/blacklist\" rel=\"noopener\">documentation<\/a>. That&#8217;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.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Managing blacklist<\/h2>\n\n\n\n<p>Let&#8217;s go through the most common actions you can perform on your blacklist: listing, adding data (numbers) and deleting it all together.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Listing blacklist<\/h3>\n\n\n\n<p>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&#8217;s start by checking your blacklist:<\/p>\n\n\n\n<script src=\"https:\/\/gist.github.com\/smsapi\/c51a1ee5fbd2bf9a741c493418660fc5.js\"><\/script>\n\n\n\n<p>We sent GET request to <strong>blacklist\/phone_numbers<\/strong> endpoint. As you can see blacklist is empty.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Adding a phone number to\nblacklist<\/h3>\n\n\n\n<p>You can continue adding a phone number to our blacklist:<\/p>\n\n\n\n<script src=\"https:\/\/gist.github.com\/smsapi\/a0910020895eb7221368995f29defee0.js\"><\/script>\n\n\n\n<p>We sent POST request to the mentioned endpoint with the <strong>phone_number<\/strong> field within. In response, we received created blacklist entry details. You can now refer to a created blacklist entry using a given id. Let&#8217;s add another phone number but this time with an expiration date defined:<\/p>\n\n\n\n<script src=\"https:\/\/gist.github.com\/smsapi\/bcba3a77bccb6516319415b6c0d1a8a8.js\"><\/script>\n\n\n\n<p>In this example response, we received another id and this time <strong>expire_at<\/strong> field is filled. Let&#8217;s look up the blacklist again:<\/p>\n\n\n\n<script src=\"https:\/\/gist.github.com\/smsapi\/140788c3256b4b2adbce449fb5967a93.js\"><\/script>\n\n\n\n<p>The collection is no longer empty. It has all the phone numbers we&#8217;ve added previously. You can check if the blacklist works:<\/p>\n\n\n\n<script src=\"https:\/\/gist.github.com\/smsapi\/b535d5a9c012b4e6d573124252cbcfa3.js\"><\/script>\n\n\n\n<p>We tried to send SMS and got an error. That&#8217;s good. This error is described: &#8216;The number is blacklisted for this user&#8217;. <a href=\"https:\/\/www.smsapi.com\/docs#18-error-codes\" target=\"_blank\" rel=\"noopener\">SMS delivery API error code description<\/a>s are listed in the documentation.<\/p>\n\n\n\n<p>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&#8217;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.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Deleting a phone number\nfrom blacklist<\/h3>\n\n\n\n<p>What if you don&#8217;t want to block blacklisted phone numbers any longer? Let&#8217;s remove it by its id:<\/p>\n\n\n\n<script src=\"https:\/\/gist.github.com\/smsapi\/041a60c22a3c6985bd16f3fc20c6d559.js\"><\/script>\n\n\n\n<p>We&#8217;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.<\/p>\n\n\n\n<p>You can also delete the whole blacklist if you wish to, but remember \u2013 this operation is irreversible:<\/p>\n\n\n\n<script src=\"https:\/\/gist.github.com\/smsapi\/9906aee575ba94fb9be473d7b33dd103.js\"><\/script>\n\n\n\n<h2 class=\"wp-block-heading\">Exporting, importing a blacklist<\/h2>\n\n\n\n<p>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):<\/p>\n\n\n\n<script src=\"https:\/\/gist.github.com\/smsapi\/500936899be549b94395152c66c5e839.js\"><\/script>\n\n\n\n<p>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.<\/p>\n\n\n\n<p>You can also import a blacklist from a file:<\/p>\n\n\n\n<script src=\"https:\/\/gist.github.com\/smsapi\/0cec97aa6ed031f02d3e721535b0739c.js\"><\/script>\n\n\n\n<p>In case of very big blacklists, you may encounter timeout issues, <a href=\"https:\/\/www.smsapi.com\/blog\/sms-gateway-starting-guide\/\" target=\"_blank\" rel=\"noreferrer noopener\">SMSAPI gateway<\/a> 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.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Summary<\/h2>\n\n\n\n<p>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!<\/p>\n","protected":false},"excerpt":{"rendered":"<p>So, do you want to exclude SMS receivers from your upcoming campaigns easily? No matter the reason: GDPR, subscription cancellation, or database maintenance, there&#8217;s a solution \u2013 our new Blacklist API.<\/p>\n","protected":false},"author":19,"featured_media":2784,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[18],"tags":[35,20,39],"class_list":["post-2783","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-tutorial","tag-database","tag-english","tag-api"],"_links":{"self":[{"href":"https:\/\/www.smsapi.com\/blog\/wp-json\/wp\/v2\/posts\/2783","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.smsapi.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.smsapi.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.smsapi.com\/blog\/wp-json\/wp\/v2\/users\/19"}],"replies":[{"embeddable":true,"href":"https:\/\/www.smsapi.com\/blog\/wp-json\/wp\/v2\/comments?post=2783"}],"version-history":[{"count":18,"href":"https:\/\/www.smsapi.com\/blog\/wp-json\/wp\/v2\/posts\/2783\/revisions"}],"predecessor-version":[{"id":5485,"href":"https:\/\/www.smsapi.com\/blog\/wp-json\/wp\/v2\/posts\/2783\/revisions\/5485"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.smsapi.com\/blog\/wp-json\/wp\/v2\/media\/2784"}],"wp:attachment":[{"href":"https:\/\/www.smsapi.com\/blog\/wp-json\/wp\/v2\/media?parent=2783"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.smsapi.com\/blog\/wp-json\/wp\/v2\/categories?post=2783"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.smsapi.com\/blog\/wp-json\/wp\/v2\/tags?post=2783"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}