Send SMS - ClearLine Documentation

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:

The third-party system prepares an SMS message for a recipient.
The third-party system sends a request to the ClearLine SMS API using the provided API key.
ClearLine validates the request and accepts the message for sending.
ClearLine returns a messageId that can be used to identify the message in future delivery status updates.
ClearLine processes the message delivery through the configured SMS delivery channel.
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.
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

{
  "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

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

{
  "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

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`

​Overview

​Message Delivery Flow

​Base flow:

​Notes

​Authentication

​Send SMS Message

​POST /MessageSender/sms

​Request Headers

​Request Body

​Example Request

​Response

​Delivery Status Callback

​Request your callback URL will receive

​Delivery Status Values

​Expected Response

​Environments