Using the SMS REST API

Archived

SMS messages are sent by making HTTP or HTTPS calls to the API. You can loop through your list of mobile numbers and make HTTP/S requests to send SMS messages to them. Generally, this API should allow you to submit up to about 100 messages per second to our platform on average (or faster if required).

It’s quick to get started and there is no need to understand the additional or advanced features unless you want to use them.

Why use this API?

• Supports JSON and XML data formats.

• Supports HTTP (port 80) and HTTPS (port 443).

• You can send to multiple handsets in one single HTTP/S request (up to 200) – this is useful if you are sending the same message text to all handsets.

• Supports persistent connections (keep-alive) and the use of multiple concurrent connections.

• Various HTTP status codes are used. Click here to view the list.

Send your first message

• Step 1: Replace the example authentication token below with your token.

• Step 2: Replace the example mobile numbers below with your number, using the correct international format. This means:

  • The mobile number needs to start with the correct country code.

  • There must be no spaces or other non-numeric characters.

  • If the mobile number starts with zero, remove the zero before typing the rest of the number.

• Step 3: Type your message text. Please note that until you make a purchase, your messages will contain pre-defined content.

curl -X POST \
-H "X-Version: 1" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer YourAuthorizationTokenHere" \
-d '{"text":"My message","to":["2799900001","2799900002"]}' \
https://api.clickatell.com/rest/message

HTTP headers explained

Header	Description	Examples
Header	Description	Examples
Authorization	Required to authenticate your API requests. The authentication token for this header is displayed in your Developers’ Central account.	Authorization: Bearer 4ZnXsl.LcQrDl4ZHWBt6_J1KLqNZVV7Tfg9KK25nd1EYaQ7SPP2mmLkODKhzJ1S
Version	Specifies which version of the API to use.	X-Version:1
Content-Type	Used to indicate whether you are submitting data in JSON or XML format. Supports application/json and application/xml. There is currently no support for x-www-form-urlencoded.	Content-Type: application/json
Accept	Used to indicate if you want a JSON or XML response format. Defaults to JSON if not specified. If specified, the API expects application/json,application/xml or */*.	Accept: application/json

Security

For added security, you can opt to:

• Use HTTPS for all API requests.

• Enable IP lockdown on your API connection.

Authenticating

All authentication is done using an authentication token (generated within Developers’ Central account). This token needs to be passed onto every REST API call. The header used for this is explained in the section called ‘HTTP Headers Explained’.