> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clearline.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Send SMS

## **Overview**

The SMS API allows you to send SMS messages and optionally receive real-time delivery status updates by providing a callback URL with each request.

## Message Delivery Flow

The SMS API allows an authorized third-party system to send SMS messages through ClearLine and optionally receive delivery status updates.

### Base flow:

1. The third-party system prepares an SMS message for a recipient.
2. The third-party system sends a request to the ClearLine SMS API using the provided API key.
3. ClearLine validates the request and accepts the message for sending.
4. ClearLine returns a `messageId` that can be used to identify the message in future delivery status updates.
5. ClearLine processes the message delivery through the configured SMS delivery channel.
6. If a `callbackUrl` was provided in the original request, ClearLine sends a delivery status callback to the specified URL when the delivery result becomes available.
7. The third-party system acknowledges the callback by returning HTTP `200 OK`.

The callback allows the third-party system to match the delivery result with the original message using the returned `messageId`.

### Notes

* The `callbackUrl` is optional. If it is not provided, the message can still be submitted for sending, but delivery status updates will not be sent back to the third-party system.
* The API key must be kept secure and must not be exposed in client-side applications or public repositories.
* The delivery status depends on the final result received from the SMS delivery channel.
* The callback endpoint should be publicly available over HTTPS and should respond with HTTP `200 OK` after successfully receiving the callback.

***

## **Authentication**

Every request must include your API key in the `ApiKey` header.

| **Header** | **Value**           |
| :--------- | :------------------ |
| `ApiKey`   | Your secret API key |

> **Keep your API key secure.** Never expose it in client-side code or public repositories.

***

## **Send SMS Message**

### `POST /MessageSender/sms`

**Base URL:** `https://api.clearline.me`

Sends an SMS message to the specified phone number. Optionally provide a `callbackUrl` to receive a delivery status notification when the message is delivered.

### **Request Headers**

| **Header**     | **Required** | **Description**                              |
| :------------- | :----------- | :------------------------------------------- |
| `ApiKey`       | Yes          | The API key used for authenticating requests |
| `Content-Type` | Yes          | `application/json`                           |

### **Request Body**

```json theme={null}
{
  "phone": "string",
  "message": "string",
  "callbackUrl": "string"
}
```

| **Field**     | **Type** | **Required** | **Description**                                                        |
| :------------ | :------- | :----------- | :--------------------------------------------------------------------- |
| `phone`       | string   | Yes          | Recipient phone number in E.164 format (e.g. `+12025551234`)           |
| `message`     | string   | Yes          | The text content of the SMS message                                    |
| `callbackUrl` | string   | No           | Your HTTPS endpoint that will receive the delivery status notification |

### **Example Request**

```http theme={null}
POST /MessageSender/sms HTTP/1.1
Host: apistage.clearline.me
ApiKey: your-api-key-here
Content-Type: application/json

{
  "phone": "+12025551234",
  "message": "Hello! Your order is ready for pickup.",
  "callbackUrl": "https://yourapp.example.com/webhooks/sms-delivery"
}
```

### **Response**

```json theme={null}
{
  "succeed": true,
  "messageId": "string"
}
```

| **Field**   | **Type** | **Description**                                  |
| :---------- | :------- | :----------------------------------------------- |
| `succeed`   | boolean  | `true` when the message was accepted for sending |
| `messageId` | string   | Unique identifier of the queued message          |

***

## **Delivery Status Callback**

When a `callbackUrl` is provided in the send request, ClearLine will call that URL with a `POST` request once the delivery status is available from the SMS gateway.

### **Request your callback URL will receive**

```http theme={null}
POST {callbackUrl} HTTP/1.1
Content-Type: application/json

{
  "messageId": "string",
  "deliveryStatus": "string",
  "externalDeliveryStatus": "string",
  "reasonText": "string"
}
```

| **Field**                | **Type** | **Description**                                                                              |
| :----------------------- | :------- | :------------------------------------------------------------------------------------------- |
| `messageId`              | string   | Matches the `messageId` returned by the send call                                            |
| `deliveryStatus`         | string   | Final resolved delivery status (e.g. `Delivered`, `DeliveredFailed`)                         |
| `externalDeliveryStatus` | string   | Raw delivery status from the SMS gateway (e.g. `Delivered`, `Failed`, `Expired`, `Rejected`) |
| `reasonText`             | string   | Human-readable delivery result description provided by the SMS gateway                       |

### **Delivery Status Values**

| `status`          | **Meaning**                        |
| :---------------- | :--------------------------------- |
| `Delivered`       | Message was successfully delivered |
| `DeliveredFailed` | Message was not delivered          |

### **Expected Response**

Your endpoint must return HTTP `200 OK` to acknowledge receipt. Any other status code will be treated as a failed delivery.

***

## **Environments**

| **Environment** | **Base URL**                    |
| :-------------- | :------------------------------ |
| Staging         | `https://apistage.clearline.me` |
| Production      | `https://api.clearline.me`      |

\\