# Using the SMS REST API

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](https://docs.clickatell.com/channels/sms-information-archived/message-status-codes/) 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**

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

### **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’.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.clickatell.com/developers-api-reference/developers-archive/sms-rest-api-overview/using-the-sms-rest-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.