Sending more than 100 000 SMS messages a month?

Phonebook API [BETA]

Phonebook API enables you to use our blacklisting feature to make sure you're not sending any unwanted messages.

API Setup

API requests are made to the following server:

https://api.messente.com/

Authentication and making requests

Requests are done with JSON body and HTTP Basic Auth is used for authentication.

Request headers example

Accept: application/json
Content-Type: application/json
Authentication: Basic QWxhZGRpbjpPcGVuU2VzYW1l

Development libraries

You can use our development libraries to help you get started quickly.

We have libraries available for the following programming languages:

Error handling

HTTP response code	Error code	Description
400	201	Missing required parameter
401	202	Authentication error
404	203	Missing resource error
409	204	Duplicate object detected
4XX (not above)	244	Client error
500	205	General error

JSON

{
    "errors": [
        {
            "code": "202",
            "detail": "User e9fbc8a9a9845 does not exist",
            "title": "Unauthorized"
        }
    ]
}

Blacklist

Blacklist is a list of numbers that is tied to one specific Account. All messages sent using any API credentials from this account, are passed through this list. If the number is in the list, the message is not sent. It applies both to API calls and messages sent from the Dashboard.

List all numbers

GET /v1/phonebook/blacklist

Successful Response

HTTP/1.1 200

{
  "phoneNumbers": [
    "+37251000000",
    "+37251000001"
  ]
}

Python
Node
PHP
Java
CURL

# pip install phonebook-api

from phonebook_api import (BlacklistApi, ApiClient, Configuration)
from phonebook_api.rest import ApiException

# Configure HTTP basic authorization: basicAuth
configuration = Configuration()
configuration.username = 'YOUR_MESSENTE_API_USERNAME'
configuration.password = 'YOUR_MESSENTE_API_PASSWORD'

# create an instance of the API class
api_instance = BlacklistApi(ApiClient(configuration))

try:
    response = api_instance.fetch_blacklist()
    print(response)
except ApiException as e:
    print("Exception when calling fetch_blacklist: %s\n" % e)

// npm install phonebook_api --save

const PhonebookApi = require('phonebook_api');

const defaultClient = PhonebookApi.ApiClient.instance;

// Configure HTTP basic authorization: basicAuth
const basicAuth = defaultClient.authentications['basicAuth'];
basicAuth.username = 'YOUR_MESSENTE_API_USERNAME';
basicAuth.password = 'YOUR_MESSENTE_API_PASSWORD';

const api = new PhonebookApi.BlacklistApi();

const callback = function(error, data, response) {
	if (error) {
		console.error(error['response']['body']);
	} else {
		console.log('API called successfully. \n', response.body);
	}
};

api.fetchBlacklist(callback);

// composer require messente/messente-phonebook-php

require_once(__DIR__ . '/vendor/autoload.php');
use Messente\Phonebook\Configuration;
use Messente\Phonebook\Api\BlacklistApi;
use GuzzleHttp\Client;

// Configure HTTP basic authorization: basicAuth
$config = Configuration::getDefaultConfiguration()
    ->setUsername('YOUR_MESSENTE_API_USERNAME')
    ->setPassword('YOUR_MESSENTE_API_PASSWORD');

$apiInstance = new BlacklistApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new Client(),
    $config
);

try {
    $response = $apiInstance->fetchBlacklist();
    echo $response;
} catch (Exception $e) {
    echo 'Exception when calling fetchBlacklist: ', $e->getMessage(), PHP_EOL;
}

// compile "com.messente.phonebook:phonebook-java"

public class BlacklistApiExample {

    public static void main(String[] args) {
        ApiClient defaultClient = Configuration.getDefaultApiClient();

        // Configure HTTP basic authorization: basicAuth
        HttpBasicAuth basicAuth = (HttpBasicAuth) defaultClient.getAuthentication("basicAuth");
        basicAuth.setUsername("YOUR_MESSENTE_API_USERNAME");
        basicAuth.setPassword("YOUR_MESSENTE_API_PASSWORD");

        BlacklistApi apiInstance = new BlacklistApi();

        try {
            FetchBlacklistSuccess response = apiInstance.fetchBlacklist();
            System.out.println(response);
        } catch (ApiException e) {
            System.err.println("Exception when calling fetchBlacklist");
            e.printStackTrace();
        }
    }
}

curl https://api.messente.com/v1/phonebook/blacklist \
    -u MESSENTE_API_USERNAME:MESSENTE_API_PASSWORD \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

Add a number

POST /v1/phonebook/blacklist

{
  "phoneNumber": "+37251000000"
}

Successful Response

HTTP/1.1 204

Python
Node
PHP
Java
CURL

# pip install phonebook-api

from phonebook_api import (BlacklistApi, ApiClient, Configuration)
from phonebook_api.rest import ApiException

# Configure HTTP basic authorization: basicAuth
configuration = Configuration()
configuration.username = 'YOUR_MESSENTE_API_USERNAME'
configuration.password = 'YOUR_MESSENTE_API_PASSWORD'

# create an instance of the API class
api_instance = BlacklistApi(ApiClient(configuration))

try:
    api_instance.add_to_blacklist({'phoneNumber': '+37255555555'})
except ApiException as e:
    print("Exception when calling add_to_blacklist: %s\n" % e)

// npm install phonebook_api --save

const PhonebookApi = require('phonebook_api');

const defaultClient = PhonebookApi.ApiClient.instance;

// Configure HTTP basic authorization: basicAuth
const basicAuth = defaultClient.authentications['basicAuth'];
basicAuth.username = 'YOUR_MESSENTE_API_USERNAME';
basicAuth.password = 'YOUR_MESSENTE_API_PASSWORD';

const api = new PhonebookApi.BlacklistApi();

const callback = function(error, data, response) {
	if (error) {
		console.error(error['response']['body']);
	} else {
		console.log('API called successfully. \n', response.body);
	}
};

api.addToBlacklist({phoneNumber: '+37255555555'}, callback);

// composer require messente/messente-phonebook-php

require_once(__DIR__ . '/vendor/autoload.php');
use Messente\Phonebook\Configuration;
use Messente\Phonebook\Api\BlacklistApi;
use GuzzleHttp\Client;

// Configure HTTP basic authorization: basicAuth
$config = Configuration::getDefaultConfiguration()
    ->setUsername('YOUR_MESSENTE_API_USERNAME')
    ->setPassword('YOUR_MESSENTE_API_PASSWORD');

$apiInstance = new BlacklistApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new Client(),
    $config
);

try {
    $apiInstance->addToBlacklist(['phoneNumber' => '+37255555555']);
} catch (Exception $e) {
    echo 'Exception when calling addToBlacklist: ', $e->getMessage(), PHP_EOL;
}

// compile "com.messente.phonebook:phonebook-java"

public class BlacklistApiExample {

    public static void main(String[] args) {
        ApiClient defaultClient = Configuration.getDefaultApiClient();

        // Configure HTTP basic authorization: basicAuth
        HttpBasicAuth basicAuth = (HttpBasicAuth) defaultClient.getAuthentication("basicAuth");
        basicAuth.setUsername("YOUR_MESSENTE_API_USERNAME");
        basicAuth.setPassword("YOUR_MESSENTE_API_PASSWORD");

        BlacklistApi apiInstance = new BlacklistApi();

        try {
            apiInstance.addToBlacklist(new NumberToBlacklist().phoneNumber("+37255555555"));
        } catch (ApiException e) {
            System.err.println("Exception when calling addToBlacklist");
            e.printStackTrace();
        }
    }
}

curl https://api.messente.com/v1/phonebook/blacklist \
    -u MESSENTE_API_USERNAME:MESSENTE_API_PASSWORD \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{ "phoneNumber": "+37255555555" }'

Check blacklist for phone number

Response if number is in blacklist

HTTP/1.1 204

or in case the number is not in blacklist

HTTP/2 404

{
  "errors": [
    {
      "code": "203",
      "detail": "the phone number was missing from the blacklist",
      "title": "Missing resource"
    }
  ]
}

Python
Node
PHP
Java
CURL

curl https://api.messente.com/v1/phonebook/blacklist/PHONE_NUMBER \
    -u MESSENTE_API_USERNAME:MESSENTE_API_PASSWORD \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

// compile "com.messente.phonebook:phonebook-java"

public class BlacklistApiExample {

    public static void main(String[] args) {
        ApiClient defaultClient = Configuration.getDefaultApiClient();

        // Configure HTTP basic authorization: basicAuth
        HttpBasicAuth basicAuth = (HttpBasicAuth) defaultClient.getAuthentication("basicAuth");
        basicAuth.setUsername("YOUR_MESSENTE_API_USERNAME");
        basicAuth.setPassword("YOUR_MESSENTE_API_PASSWORD");

        BlacklistApi apiInstance = new BlacklistApi();

        try {
            apiInstance.isBlacklisted("+37255555555");
        } catch (ApiException e) {
            System.err.println("Exception when calling isBlacklisted");
            e.printStackTrace();
        }
    }
}

// npm install phonebook_api --save

const PhonebookApi = require('phonebook_api');

const defaultClient = PhonebookApi.ApiClient.instance;

// Configure HTTP basic authorization: basicAuth
const basicAuth = defaultClient.authentications['basicAuth'];
basicAuth.username = 'YOUR_MESSENTE_API_USERNAME';
basicAuth.password = 'YOUR_MESSENTE_API_PASSWORD';

const api = new PhonebookApi.BlacklistApi();

const callback = function(error, data, response) {
	if (error) {
		console.error(error['response']['body']);
	} else {
		console.log('API called successfully. \n', response.body);
	}
};

api.isBlacklisted('+37255555555', callback);

// composer require messente/messente-phonebook-php

require_once(__DIR__ . '/vendor/autoload.php');
use Messente\Phonebook\Configuration;
use Messente\Phonebook\Api\BlacklistApi;
use GuzzleHttp\Client;

// Configure HTTP basic authorization: basicAuth
$config = Configuration::getDefaultConfiguration()
    ->setUsername('YOUR_MESSENTE_API_USERNAME')
    ->setPassword('YOUR_MESSENTE_API_PASSWORD');

$apiInstance = new BlacklistApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new Client(),
    $config
);

try {
    $apiInstance->isBlacklisted('+37255555555');
} catch (Exception $e) {
    echo 'Exception when calling isBlacklisted: ', $e->getMessage(), PHP_EOL;
}

# pip install phonebook-api

from phonebook_api import (BlacklistApi, ApiClient, Configuration)
from phonebook_api.rest import ApiException

# Configure HTTP basic authorization: basicAuth
configuration = Configuration()
configuration.username = 'YOUR_MESSENTE_API_USERNAME'
configuration.password = 'YOUR_MESSENTE_API_PASSWORD'

# create an instance of the API class
api_instance = BlacklistApi(ApiClient(configuration))

try:
    api_instance.is_blacklisted('+37255555555')
except ApiException as e:
    print("Exception when calling remove_from_blacklist: %s\n" % e)

Delete a phone number

DELETE /v1/phonebook/blacklist/{phone-number}

Successful Response

HTTP/1.1 204

Python
Node
PHP
Java
CURL

# pip install phonebook-api

from phonebook_api import (BlacklistApi, ApiClient, Configuration)
from phonebook_api.rest import ApiException

# Configure HTTP basic authorization: basicAuth
configuration = Configuration()
configuration.username = 'YOUR_MESSENTE_API_USERNAME'
configuration.password = 'YOUR_MESSENTE_API_PASSWORD'

# create an instance of the API class
api_instance = BlacklistApi(ApiClient(configuration))

try:
    api_instance.remove_from_blacklist('+37255555555')
except ApiException as e:
    print("Exception when calling remove_from_blacklist: %s\n" % e)

// npm install phonebook_api --save

const PhonebookApi = require('phonebook_api');

const defaultClient = PhonebookApi.ApiClient.instance;

// Configure HTTP basic authorization: basicAuth
const basicAuth = defaultClient.authentications['basicAuth'];
basicAuth.username = 'YOUR_MESSENTE_API_USERNAME';
basicAuth.password = 'YOUR_MESSENTE_API_PASSWORD';

const api = new PhonebookApi.BlacklistApi();

const callback = function(error, data, response) {
	if (error) {
		console.error(error['response']['body']);
	} else {
		console.log('API called successfully. \n', response.body);
	}
};

api.removeFromBlacklist('+37255555555', callback);

// composer require messente/messente-phonebook-php

require_once(__DIR__ . '/vendor/autoload.php');
use Messente\Phonebook\Configuration;
use Messente\Phonebook\Api\BlacklistApi;
use GuzzleHttp\Client;

// Configure HTTP basic authorization: basicAuth
$config = Configuration::getDefaultConfiguration()
    ->setUsername('YOUR_MESSENTE_API_USERNAME')
    ->setPassword('YOUR_MESSENTE_API_PASSWORD');

$apiInstance = new BlacklistApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new Client(),
    $config
);

try {
    $apiInstance->removeFromBlacklist('+37255555555');
} catch (Exception $e) {
    echo 'Exception when calling removeFromBlacklist: ', $e->getMessage(), PHP_EOL;
}

// compile "com.messente.phonebook:phonebook-java"

public class BlacklistApiExample {

    public static void main(String[] args) {
        ApiClient defaultClient = Configuration.getDefaultApiClient();

        // Configure HTTP basic authorization: basicAuth
        HttpBasicAuth basicAuth = (HttpBasicAuth) defaultClient.getAuthentication("basicAuth");
        basicAuth.setUsername("YOUR_MESSENTE_API_USERNAME");
        basicAuth.setPassword("YOUR_MESSENTE_API_PASSWORD");

        BlacklistApi apiInstance = new BlacklistApi();

        try {
            apiInstance.removeFromBlacklist("+37255555555");
        } catch (ApiException e) {
            System.err.println("Exception when calling removeFromBlacklist");
            e.printStackTrace();
        }
    }
}

curl https://api.messente.com/v1/phonebook/blacklist/PHONE_NUMBER \
    -u MESSENTE_API_USERNAME:MESSENTE_API_PASSWORD \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"
    -X "DELETE"

Home

Getting Started

Changelog

API Setup

SMS Messaging API

OmniChannel API

2FA API

Number Lookup BETA

Number Verification DEPRECATED

Pricing API

Phonebook API BETA

Account Balance API

Tools

FAQ

Phonebook API [BETA]

API Setup

Authentication and making requests

Request headers example

Development libraries

Error handling

Blacklist

List all numbers

Successful Response

Add a number

Successful Response

Check blacklist for phone number

Delete a phone number

Successful Response

What's next?

Explore Messaging API features

Try out Two-Step Authentication

Read more about multi-channel messages

Check out our pricing

Search results