SMS (1.0.0)

You can use the SMS endpoints to send and manage SMS, check the cost of sending SMS, view message history, and more. Integrate them into your system as part of your workflow.

Relevant guides: How many characters can I send in an SMS?, SMS status delivery receipt expired, Do you support non-English characters, and Country Specific Features and Restrictions.

Send SMS

Use this endpoint to send messages to your recipients, who can be either a phone number or a contact from your contact list. The sender of the message (Sender ID) can be a shared number, a dedicated number, alpha tags (business name), or your own number. You can send messages both locally and globally, subject to the country restrictions. The cost of sending messages varies based on the type and length of the message.

Request
header Parameters
Content-Type
string
Example: application/json
Request Body schema: application/json
Array of objects

Messages to send to customers.

Responses
200

Successful response

post/v3/sms/send
Request samples
application/json
{
  • "messages": [
    ]
}
Response samples
application/json
{
  • "http_code": 200,
  • "response_code": "SUCCESS",
  • "response_msg": "Messages queued for delivery.",
  • "data": {
    }
}

Calculate SMS Price

Use this endpoint to calculate the price of sending a message. The cost of sending messages varies based on the type and length of the message.

Properties

Name Type Required Restrictions Description
from string true yes Your sender id
body string true none Your message.
to string true none Recipient phone number in E.164 format.
source string false none Your method of sending e.g. 'wordpress', 'php', 'c#'.
schedule integer(int32) false none Leave blank for immediate delivery. Your schedule time in unix format http://help.clicksend.com/what-is-a-unix-timestamp
custom_string string false none Your reference. Will be passed back with all replies and delivery reports.
list_id integer(int32) false none Your list ID if sending to a whole list. Can be used instead of 'to'.
country string false none ISO alpha-2 character country code e.g. 'US', we use this to format the recipient number if it's not in international format.
from_email string false none An email address where the reply should be emailed to. If omitted, the reply will be emailed back to the user who sent the outgoing SMS.

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication, more info...
Request
header Parameters
Content-Type
string
Example: application/json
Request Body schema: application/json
object
Responses
200

Successful response

post/v3/sms/price
Request samples
application/json
{
  • "messages": [
    ]
}
Response samples
application/json
{
  • "http_code": 200,
  • "response_code": "SUCCESS",
  • "response_msg": "Here are your data.",
  • "data": {
    }
}

Create Test SMS Receipt

Use this endpoint to test if the delivery report rule is working by sending a test SMS. This rule notifies you about any outgoing SMS sent from your account. When you send an SMS, the carrier sends a receipt back to ClickSend, and you can choose to be notified. You can receive notifications via webhook to your server or by polling ClickSend’s system.

Properties

Name Type Required Restrictions Description
url string true none Your URL that you want to forward to.

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication, more info...
Request
header Parameters
Content-Type
string
Example: application/json
Request Body schema: application/json
object
Responses
200

Successful response

post/v3/sms/receipts
Request samples
application/json
{
  • "url": "testURL"
}
Response samples
application/json
{
  • "http_code": 200,
  • "response_code": "SUCCESS",
  • "response_msg": "Receipt has been added",
  • "data": {
    }
}

View SMS Receipts

Use this endpoint to retrieve the outgoing SMS from the ClickSend’s system. You can specify the number of outgoing SMS to retrieve in the query parameters.

Push Delivery Receipts

If you prefer, we can push message replies to your server as they arrive with us.

  1. Log into your account.
  2. Click on your profile on the top right.
  3. Then click on the Messaging Settings option.
  4. Click on SMS & MMS then Delivery Report Rules.
  5. Click the 'Add New Rule' button.
  6. Select the 'URL' action.
  7. Enter the URL and click 'Save'.

The following variables will be posted to the URL specified:

Variable Description
timestamp_send Timestamp of the original send request in UNIX format. e.g 1439173980
timestamp Timestamp of delivery report in UNIX format. e.g 1439173981
message_id Message ID, returned when originally sending the message.
status Delivered or Undelivered
status_code Status code. Refer to 'SMS Delivery Status Codes' in docs.
status_text Status text.
error_code Error code.
error_text Error text.
custom_string A custom string used when sending the original message.
user_id The user ID of the user who sent the message.
subaccount_id The subaccount ID of the user who sent the message.
message_type 'sms' (constant).

Pull Delivery Receipts

Receive delivery reports by polling. You can poll our server and retrieve delivery reports at a time that suits you.

After pulling your unread SMS delivery receipts from your inbox you will need to call the Mark SMS Delivery Receipt As Read endpoint in order to continue viewing your unread delivery receipts.

  1. Log into your account.
  2. Click on your profile on the top right.
  3. Then click on the Messaging Settings option.
  4. Click on SMS & MMS then Delivery Report Rules.
  5. Click the 'Add New Rule' button.
  6. Select the 'Poll' action.
  7. Then click 'Save'.

Parameters

Parameter In Type Required Description
page query integer(int32) false Page number
limit query integer(int32) false Number of records per page

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication, more info...
Request
header Parameters
Content-Type
string
Example: application/json
Responses
200

Successful response

get/v3/sms/receipts
Request samples
curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \

'https://rest.clicksend.com/v3/sms/receipts'
Response samples
application/json
{
  • "http_code": 200,
  • "response_code": "SUCCESS",
  • "response_msg": "Here are your delivery receipts.",
  • "data": {
    }
}

View Specific SMS Receipt

Use this endpoint to retrieve a specific outgoing SMS from the ClickSend’s system.

Parameters

Parameter In Type Required Description
message_id path string true Message ID

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication, more info...
Request
path Parameters
message_id
required
string
header Parameters
Content-Type
string
Example: application/json
Responses
200

Successful response

get/v3/sms/receipts/{message_id}
Request samples
curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \

'https://rest.clicksend.com/v3/sms/receipts/{message_id}'
Response samples
application/json
{
  • "http_code": 200,
  • "response_code": "SUCCESS",
  • "response_msg": "Your receipt.",
  • "data": {
    }
}

Mark SMS Receipt As Read

Use this endpoint to mark outgoing SMS from the ClickSend’s system as read. Once the SMS are read, you'll not be able to view it again using the View SMS Receipts or View Specific SMS Receipt.

Parameters

Parameter In Type Required Description
date_before body integer(int32) false Mark all as read before this timestamp

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication, more info...
Request
header Parameters
Content-Type
string
Example: application/json
Request Body schema: application/json
object
Responses
200

Successful response

put/v3/sms/receipts-read
Request samples
application/json
{
  • "date_before": "1961900166"
}
Response samples
application/json
{
  • "http_code": 200,
  • "response_code": "SUCCESS",
  • "response_msg": "Receipts has been marked as read.",
  • "data": [ ]
}

Create Test Inbound SMS

Use this endpoint to test if the inbound rule is working by sending a test incoming SMS. This rule notifies you about any incoming SMS sent to your Sender ID, exluding SMS sent to Alpha tags as they cannot receive inbound SMS. When your receipient replies with an SMS, the carrier sends a message back to ClickSend, and you can choose to be notified. You can receive notifications via webhook to your server or by polling ClickSend’s system.

Properties

Name Type Required Restrictions Description
url string true none Your URL that you want to forward to.

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication, more info...
Request
header Parameters
Content-Type
string
Example: application/json
Request Body schema: application/json
object
Responses
200

Successful response

post/v3/sms/inbound
Request samples
application/json
{
  • "url": "poll"
}
Response samples
application/json
{
  • "http_code": 200,
  • "response_code": "SUCCESS",
  • "response_msg": "Here are your incoming messages.",
  • "data": {
    }
}

View Inbound SMS

Use this endpoint to retrieve the inbound SMS from the ClickSend’s system. You can specify the number of inbound SMS to retrieve in the query parameters.

Push Inbound SMS

If you prefer, we can push message replies to your server as they arrive with us.

  1. Log into your account.
  2. Click on your profile on the top right.
  3. Then click on the Messaging Settings option.
  4. Click on SMS & MMS then Inbound Rules.
  5. Click the 'Add New Rule' button.
  6. Select the 'URL' action.
  7. Enter the URL and click 'Save'.

The following variables will be posted to the URL specified:

Variable Description
timestamp Timestamp in UNIX format. e.g 1439173981
to Number that the SMS was sent to (your Dedicated or shared number).
from Recipient Mobile Number that sent the reply message.
body Inbound message body.
original_body Original outgoing SMS message body.
original_message_id Original SMS message ID. Returned when originally sending the message.
custom_string A custom string used when sending the original message.
user_id The user ID of the user who sent the message.
subaccount_id The subaccount ID of the user who sent the message.
message_id The Message ID for the inbound message.

Note: HTTP POST is used to send the variables (not GET or query-string). More Info.

Your URL should respond with a 200 OK HTTP status code. If we receive a non-200 response or your URL is down/times out, we will continue to retry every 10 minutes (with a timeout of 30 seconds) until we reach 10 retries. After 10 attempts, we'll mark it as completed. If your server is down for a long period of time, we can manually re-queue the data.

Pull Inbound SMS

Receive SMS by polling your Inbox. You can poll our server and retrieve new Messages at a time that suits you.

After pulling an inbound SMS from your inbox you will need to call the Mark Inbound SMS As Read endpoint in order to continue viewing your unread inbound messages.

  1. Log into your account.
  2. Click on your profile on the top right.
  3. Then click on the Messaging Settings option.
  4. Click on SMS & MMS then Inbound Rules.
  5. Click the 'Add New Rule' button.
  6. Select the 'Poll' action.
  7. Then click 'Save'.

Parameters

Parameter In Type Required Description
page query integer(int32) false Page number
limit query integer(int32) false Number of records per page

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication, more info...
Request
header Parameters
Content-Type
string
Example: application/json
Responses
200

Successful response

get/v3/sms/inbound
Request samples
curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \

'https://rest.clicksend.com/v3/sms/inbound'
Response samples
application/json
{
  • "http_code": 200,
  • "response_code": "SUCCESS",
  • "response_msg": "Here are your data.",
  • "data": {
    }
}

Mark Inbound SMS as Read

Use this endpoint to mark inbound SMS from the ClickSend’s system as read. Once the SMS are read, you'll not be able to view it again using the View Inbound SMS.

Mark all inbound SMS as read optionally before a certain date

Parameters

Parameter In Type Required Description
date_before body integer(int32) false An optional timestamp - mark all as read before this timestamp. If not given, all messages will be marked as read.

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication, more info...
Request
header Parameters
Content-Type
string
Example: application/json
Request Body schema: application/json
object
Responses
200

Successful response

put/v3/sms/inbound-read
Request samples
application/json
{
  • "date_before": "1961900166"
}
Response samples
application/json
{
  • "http_code": 200,
  • "response_code": "SUCCESS",
  • "response_msg": "Inbound messages have been marked as read.",
  • "data": [ ]
}

Mark Specific Inbound SMS Message As Read

Use this endpoint to mark a specific inbound SMS from the ClickSend’s system as read. Once the SMS is read, you'll not be able to view it again using the View Inbound SMS.

Parameters

Parameter In Type Required Description
message_id path String true Mark this message as read

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication, more info...
Request
path Parameters
message_id
required
string
header Parameters
Content-Type
string
Example: application/json
Request Body schema: application/json
object
Responses
200

Successful response

put/v3/sms/inbound-read/{message_id}
Request samples
application/json
""
Response samples
application/json
{
  • "http_code": 200,
  • "response_code": "SUCCESS",
  • "response_msg": "Receipt have been marked as read.",
  • "data": 1
}

Cancel SMS

Use this endpoint to cancel a pending SMS that hasn't been delivered yet.

Parameters

Parameter In Type Required Description
message_id path string true The message ID you want to cancel

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication, more info...

Request
path Parameters
message_id
required
string
header Parameters
Content-Type
string
Example: application/json
Request Body schema: application/json
object
Responses
200

Successful response

put/v3/sms/{message_id}/cancel
Request samples
application/json
""
Response samples
application/json
{
  • "http_code": 200,
  • "response_code": "SUCCESS",
  • "response_msg": "string",
  • "data": [ ]
}

Cancel All SMS

Use this endpoint to cancel all pending SMS that haven't been delivered yet.

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication, more info...
Request
header Parameters
Content-Type
string
Example: application/json
Request Body schema: application/json
object
Responses
200

Successful response

put/v3/sms/cancel-all
Request samples
application/json
""
Response samples
application/json
{
  • "http_code": 200,
  • "response_code": "SUCCESS",
  • "response_msg": "5 messages has been cancelled.",
  • "data": {
    }
}

View SMS Templates

Use this endpoint to view templates that you’ve made. You can specify the number of templates to retrieve in the query parameters.

Parameters

Parameter In Type Required Description
page query integer(int32) false Page number
limit query integer(int32) false Number of records per page

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication, more info...
Request
header Parameters
Content-Type
string
Example: application/json
Responses
200

Successful response

get/v3/sms/templates
Request samples
curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \

'https://rest.clicksend.com/v3/sms/templates'
Response samples
application/json
{
  • "http_code": 200,
  • "response_code": "SUCCESS",
  • "response_msg": "Here are your data.",
  • "data": {
    }
}

Create SMS Template

Use this endpoint to create a template that you can use for sending SMS.

Properties

Name Type Required Restrictions Description
template_name string true none Name of template
body string true none Body of template

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication, more info...
Request
header Parameters
Content-Type
string
Example: application/json
Request Body schema: application/json
object
Responses
200

Successful response

post/v3/sms/templates
Request samples
application/json
{
  • "template_name": "Template 501916",
  • "body": "This is a test template.\r\nnew line 漢字 here."
}
Response samples
application/json
{
  • "http_code": 200,
  • "response_code": "SUCCESS",
  • "response_msg": "New template has been saved.",
  • "data": {
    }
}

Update SMS Template

Use this endpoint to update an existing template.

Parameters

Parameter In Type Required Description
template_id path integer(int32) true Template id

Properties

Name Type Required Restrictions Description
template_name string true none Name of template
body string true none Body of template

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication, more info...
Request
path Parameters
template_id
required
string
header Parameters
Content-Type
string
Example: application/json
Request Body schema: application/json
object
Responses
200

Successful response

put/v3/sms/templates/{template_id}
Request samples
application/json
{
  • "template_name": "Template 501916",
  • "body": "This is a test updated template.\r\nnew line 漢字 here."
}
Response samples
application/json
{
  • "http_code": 200,
  • "response_code": "SUCCESS",
  • "response_msg": "Your template has been updated.",
  • "data": {
    }
}

Delete SMS Template

Use this endpoint to delete an existing template.

Parameters

Parameter In Type Required Description
template_id path integer(int32) true Template id

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication, more info...
Request
path Parameters
template_id
required
string
header Parameters
Content-Type
string
Example: application/json
Responses
200

Successful response

delete/v3/sms/templates/{template_id}
Request samples
curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \
     --request DELETE \

'https://rest.clicksend.com/v3/sms/templates/{template_id}'
Response samples
application/json
{
  • "http_code": 200,
  • "response_code": "SUCCESS",
  • "response_msg": "Your template has been deleted.",
  • "data": [ ]
}

View SMS History

Use this endpoint to view previously sent SMS. You can specify the number of SMS to retrieve using the query parameters.

Parameters

Parameters In Type Required Description
date_from query integer(int32) false Start date (Unix Timestamp e.g. 1436849372)
date_to query integer(int32) false End date (Unix Timestamp e.g. 1436879372)
page query integer(int32) false Page number
limit query integer(int32) false Number of records per page

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication, more info...
Request
header Parameters
Content-Type
string
Example: application/json
Responses
200

Successful response

get/v3/sms/history
Request samples
curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \

'https://rest.clicksend.com/v3/sms/history?date_from=&date_to='
Response samples
application/json
{
  • "http_code": 200,
  • "response_code": "SUCCESS",
  • "response_msg": "Here are your data.",
  • "data": {
    }
}

Export SMS History

Use this endpoint to generate a download link for accessing the history of previously sent SMS. You can specify the number of SMS to retrieve using the query parameters.

Parameters

Parameter In Type Required Description
filename query string true Filename to download history as

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication, more info...
Request
query Parameters
filename
string
Example: filename=SMS_history.csv
q
string
order_by
string
Example: order_by=date:desc
date_from
string
date_to
string
limit
string
Example: limit=50000
header Parameters
Content-Type
string
Example: application/json
Responses
200

Successful response

get/v3/sms/history/export
Request samples
curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \

'https://rest.clicksend.com/v3/sms/history/export?filename={filename}'
Response samples
application/json
{}
Copyright © ClickSend 2024. All right reserved.