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.

ClickSend is pausing SMS messages containing URLs for new customers. Please remove links from messages to maintain uninterrupted delivery, or contact support to apply for approval for URL messaging.

Send SMS

Use this endpoint to send messages to your recipients, either as phone numbers or contacts from your contact list. The sender of the message (Sender ID) can be a shared number, a dedicated number, alpha tag (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 (senders)

The senders property specifies sender IDs for each recipient country.

  • Want to leverage the default sender settings:

    • If the senders property is missing or left empty, the system uses the default sender settings configured for each recipient country.

  • Want to override the default sender settings:

    • When the senders property is provided, it should contain valid sender IDs for each recipient country listed under recipients. These IDs will override the default sender settings for the specified countries.
    • If an invalid sender ID is provided, or a sender ID for a specific recipient country is missing, the system will revert to using the default sender settings for that country.
The senders parameter is currently in beta and available only to beta testing users.

Join the BETA Program:

Early access to Smart Assign is available. Contact the sales team to opt-in and participate in the BETA program.

shorten_urls
boolean (shorten_urls)

This controls whether URLs are automatically shortened. This affects all messages in the request. You can either specify:

  • True - Automatically detects and shortens one URL on each message.
  • False - Leaves all URLs in their original form. This is the default value.

More info about shortening URLs here.

Array of objects

Messages to send to customers.

Responses
200

Successful response

post/v3/sms/send
Request samples
application/json
{
  • "senders": [
    ],
  • "shorten_urls": false,
  • "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 messages. 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 (senders)

The senders property specifies sender IDs for each recipient country.

  • Want to leverage the default sender settings:

    • If the senders property is missing or left empty, the system uses the default sender settings configured for each recipient country.

  • Want to override the default sender settings:

    • When the senders property is provided, it should contain valid sender IDs for each recipient country listed under recipients. These IDs will override the default sender settings for the specified countries.
    • If an invalid sender ID is provided, or a sender ID for a specific recipient country is missing, the system will revert to using the default sender settings for that country.
The senders parameter is currently in beta and available only to beta testing users.

Join the BETA Program:

Early access to Smart Assign is available. Contact the sales team to opt-in and participate in the BETA program.

shorten_urls
boolean (shorten_urls)

This controls whether URLs are automatically shortened. This affects all messages in the request. You can either specify:

  • True - Automatically detects and shortens one URL on each message.
  • False - Leaves all URLs in their original form. This is the default value.

More info about shortening URLs here.

Array of objects

Messages to send to customers.

Responses
200

Successful response

post/v3/sms/price
Request samples
application/json
{
  • "senders": [
    ],
  • "shorten_urls": false,
  • "messages": [
    ]
}
Response samples
application/json
{
  • "http_code": 200,
  • "response_code": "SUCCESS",
  • "response_msg": "Here is some pricing.",
  • "data": {
    }
}

Create Test SMS Receipt

Use this endpoint to generate and send a test SMS delivery receipt to your webhook URL. When you send an SMS, a delivery receipt is generated and can be received at your webhook URL. This test endpoint allows you to verify that the receipt is correctly sent to your webhook URL.

Additionally, you can obtain SMS receipts by setting the webhook URL to poll and periodically calling the View SMS Receipt endpoint to check for new receipts. This process is known as polling.

Request
header Parameters
Content-Type
string
Example: application/json
Request Body schema: application/json
url
required
string

The webhook URL where the delivery receipt will be sent to. You can set the value to poll to send it to the ClickSend
system, and then retrieve it with the View SMS Receipt endpoint

Note:

You can create a webhook URL in Pipedream to test receiving the SMS receipt. Follow the instructions here.

Responses
200

Successful response

post/v3/sms/receipts
Request samples
application/json
{}
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 SMS delivery receipts sent by your recipient. To be able to view receipts, add a delivery report rule with the Action set to POLL in the Dashboard, or use the Create SMS Delivery Receipt Rule endpoint. Control pagination with the page and limit query parameters to specify the page of results and the number of items returned.

Request
query Parameters
page
integer
Default: 1

The page number to retrieve. Use this parameter to navigate through the pagination results. The default value is 1.

Example: page=1
limit
integer [ 15 .. 100 ]
Default: 15

The number of items to return per page. This parameter controls the size of each page of results. The default value is 15.

Example: limit=15
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 SMS delivery receipt, including those that have been marked as read. When you send an SMS, a delivery receipt is generated and can be received. This endpoint enables you to retrieve those receipts.

Request
path Parameters
message_id
required
string

The message_id of the SMS delivery reciept to retrieve

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 all SMS delivery receipts as read. Delivery receipts that have been marked as read won’t be shown in the View SMS Receipts endpoint. You can still use the View Specific SMS Receipt endpoint to view delivery receipts marked as read. In the request, you can optionally add a date_before parameter to only mark receipts sent before that date as read

Request
header Parameters
Content-Type
string
Example: application/json
Request Body schema: application/json
date_before
integer

The cutoff date. Receipts sent before this time will be marked as read. It’s in the Unix format.

Responses
200

Successful response

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

Create Test Inbound SMS

Use this endpoint to generate and send a test inbound SMS to your webhook URL. Inbound SMS are messages sent by your recipient to you. This test endpoint allows you to verify that the inbound SMS is correctly sent to your webhook URL.

Request
header Parameters
Content-Type
string
Example: application/json
Request Body schema: application/json
url
required
string

The webhook URL where the inbound SMS will be sent to.

Note:

You can create a webhook URL in Pipedream to test receiving the inbound SMS. Follow the instructions here.

webhook_type
string

Specifies the HTTP method used when the webhook sends a request to the URL. The available options are:

  • post (Default): Sends the event data using an HTTP POST request.

  • get: Sends the event data as query parameters in an HTTP GET request.

  • json: Sends the event data using a custom JSON format (via a POST request).

This parameter is used to determine how the data will be transmitted, depending on your preferred method and how the receiving system is designed to process incoming requests.

Responses
200

Successful response

post/v3/sms/inbound
Request samples
application/json
{}
Response samples
application/json
{
  • "http_code": 200,
  • "response_code": "SUCCESS",
  • "response_msg": "Test inbound message has been added.",
  • "data": {
    }
}

View Inbound SMS

Use this endpoint to retrieve SMS delivery receipts sent by your recipient. To be able to view receipts, add a inbound rule with the Action set to POLL in the Dashboard, or use the Create SMS Inbound Automation endpoint. Control pagination with the page and limit query parameters to specify the page of results and the number of items returned.

Note:

If you have multiple inbound rules set to POLL, you will receive the inbound message multiple times.

Request
query Parameters
page
integer
Default: 1

The page number to retrieve. Use this parameter to navigate through the pagination results. The default value is 1.

Example: page=1
limit
integer [ 15 .. 100 ]
Default: 15

The number of items to return per page. This parameter controls the size of each page of results. The default value is 15.

Example: limit=15
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": {
    }
}

View a specific inbound SMS message

Use this endpoint to retrieve a specific inbound SMS, including those that have been marked as read. Inbound SMS are messages sent by your recipient to you. This endpoint enables you to retrieve those inbound SMS.

Request
path Parameters
original_message_id
required
string

The original_message_id of the inbound SMS to view. If the recipient replied with multiple messages, this endpoint returns the first inbound SMS received.

Note:

When you receive an inbound message, you will get two parameters: original_message_id and message_id:

  • original_message_id: This is the ID of the outbound message sent to the recipient
  • message_id: This is the ID of the inbound message sent by the recipient.
header Parameters
Content-Type
string
Example: application/json
Responses
200

Successful response

get/v3/sms/inbound/{original_message_id}
Request samples 
curl --location 'https://rest.clicksend.com/v3/sms/inbound/{original_message_id}' \
--header 'Content-Type: application/json' \
--header 'Authorization: API_KEY'
Response samples
application/json
{
  • "http_code": 200,
  • "response_code": "SUCCESS",
  • "response_msg": "Here are your result.",
  • "data": {
    }
}

Mark Inbound SMS as Read

Use this endpoint to mark all inbound SMS as read. Inbound SMS that has been marked as read won’t be shown in the View Inbound SMS endpoint. You can still use the View Specific Inbound SMS endpoint to view inbound SMS marked as read. In the request, you can optionally add a date_before parameter to only mark inbound SMS sent before that date as read.

Request
header Parameters
Content-Type
string
Example: application/json
Request Body schema: application/json
date_before
integer

The cutoff date. Inbound SMS sent before this time will be marked as read. It’s in the Unix format.

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": null
}

Mark Specific Inbound SMS Message As Read

Use this endpoint to mark a specific inbound SMS as read. Unlike the View Inbound SMS endpoint, which marks all inbound SMS as read, this endpoint only marks one specified inbound SMS. Specify the SMS to be marked as read by providing its message_id.

Request
path Parameters
message_id
required
string

The message_id of the inbound SMS to mark as read.

Note:

When you receive an inbound message, you will get two parameters: original_message_id and message_id:

  • original_message_id: This is the ID of the outbound message sent to the recipient
  • message_id: This is the ID of the inbound message sent by the recipient.
header Parameters
Content-Type
string
Example: application/json
Responses
200

Successful response

put/v3/sms/inbound-read/{message_id}
Request samples 
curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \
     --request PUT \
'https://rest.clicksend.com/v3/sms/inbound-read/{message_id}'
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 specific scheduled SMS. Unlike the Cancel All SMS endpoint, which cancels all scheduled SMS, this endpoint only cancels one specified scheduled SMS. Specify the scheduled SMS to cancel by providing its message_id.

Request
path Parameters
message_id
required
string

The message_id of the scheduled SMS to cancel.

header Parameters
Content-Type
string
Example: application/json
Responses
200

Successful response

put/v3/sms/{message_id}/cancel
Request samples 
curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \
     --request PUT \

'https://rest.clicksend.com/v3/sms/{message_id}/cancel'
Response samples
application/json
{
  • "http_code": 200,
  • "response_code": "SUCCESS",
  • "response_msg": "Scheduled sms message has been cancelled.",
  • "data": null
}

Cancel All SMS

Use this endpoint to cancel all scheduled SMS. To cancel only one scheduled SMS, use the Cancel SMS endpoint.

Request
header Parameters
Content-Type
string
Example: application/json
Request Body schema: application/json
custom_string
string

The scheduled messages to cancel with the specified custom_string. When you send an SMS, you can add an optional custom_string to it. This parameter allows you to cancel messages that have this custom_string.

It's commonly used for canceling scheduled SMS campaigns. When you send an SMS campaign, the system automatically adds a custom_string to each message, and this parameter lets you cancel only those specific messages.

Responses
200

Successful response

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

View SMS Templates

Use this endpoint to retrieve SMS templates. You can filter the SMS templates result using the query parameters.

Request
query Parameters
page
integer
Default: 1

The page number to retrieve. Use this parameter to navigate through the pagination results. The default value is 1.

Example: page=1
limit
integer [ 15 .. 100 ]
Default: 15

The number of items to return per page. This parameter controls the size of each page of results. The default value is 15.

Example: limit=15
q
string
Default: "field_name"

Allows filtering of results based on your search criteria. The query should be in the format field_name:value.

  1. Field Name: The field within the SMS history you want to filter by. You can use the following fields:
  • template_id : The ID of the template
  • template_name : The name of the template
  • body : The body content of the template.
  1. Value: The text or keyword you're searching for within the specified field. If left empty after the colon, the filter will look for all templates with any value in the Field Name.

For example, if you are searching for the template with the name of sample_name, the final query would look like this:

q=template_name:sample_name

Note:

Some characters have to be encoded. For example, if you are searching for SMS sent from the phone number +61437085284, your search query q would be:

  • q=from:%2B61437085284

You can use the URL encoder to encode the text. If a character is not an alphanumeric character (A-Z, a-z, 0-9), it is typically either reserved or unsafe and should be encoded.

order_by
string
Default: "template_id:asc"

Specifies the field and order to sort the results by. The value is composed of the field name followed by a colon and the sort direction (asc for ascending or desc for descending). The default sort order is by template_id in ascending order. You can use the following fields:

  • template_id : The ID of the Template
  • template_name : The name of the Template
  • body : The body content of the Template

For example, if you want to order by the template_id in descending order, the query would look like this:

order_by=template_id:desc

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 templates.",
  • "data": [
    ]
}

Create SMS Template

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

Request
header Parameters
Content-Type
string
Example: application/json
Request Body schema: application/json
template_name
string

The name of the template.

body
string

body String The main content of your template.

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

View a Specific SMS Template

Use this endpoint to retrieve a SMS template. Specify which template to retrieve using the template ID.

Request
path Parameters
template_id
required
string

The ID of the template to retrieve

header Parameters
Content-Type
string
Example: application/json
Responses
200

Successful response

get/v3/sms/templates/{template_id}
Request samples 
curl --location --globoff 'https://rest.clicksend.com/v3/sms/templates/{{templateId}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: [API_KEY]'
Response samples
application/json
{
  • "http_code": 200,
  • "response_code": "SUCCESS",
  • "response_msg": "Here is your template.",
  • "data": {
    }
}

Update SMS Template

Use this endpoint to update a SMS template.

Request
path Parameters
template_id
required
string

The ID of the template to update.

header Parameters
Content-Type
string
Example: application/json
Request Body schema: application/json
template_name
string

The new name of the template.

body
string

The new content of your template.

Responses
200

Successful response

put/v3/sms/templates/{template_id}
Request samples
application/json
{
  • "template_name": "Template XYZ",
  • "body": "This is a new update template"
}
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 a SMS template. Specify the SMS template to delete by providing its template_id.

Request
path Parameters
template_id
required
string

The ID of the template to delete.

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": null
}

View SMS History

Use this endpoint to view previously sent SMS. You can filter the SMS history result using the query parameters.

Request
query Parameters
page
integer
Default: 1

The page number to retrieve. Use this parameter to navigate through the pagination results. The default value is 1.

Example: page=1
limit
integer [ 15 .. 100 ]
Default: 15

The number of items to return per page. This parameter controls the size of each page of results. The default value is 15.

Example: limit=15
q
string
Default: "field_name"

Allows filtering of results based on your search criteria. The query should be in the format field_name:value.

  1. Field Name: The field within the SMS history you want to filter by. You can use the following fields:

    • Status: The status of the SMS. Available values for status are: Queued, Completed, Scheduled, WaitApproval, Failed, Cancelled, CancelledAfterReview, Received, Sent.

    • To: The recipient of the SMS.

    • from: The sender of the SMS.

    • subaccount_id: The sub-account identifier.

    • message_id: The ID of your SMS.

  2. Value: The text or keyword you're searching for within the specified field. If left empty after the colon, the filter will look for all templates with any value in the Field Name.

For example, if you are searching for a SMS with the status of Scheduled, the final query would look like this:

q=status:Scheduled

Note:

Some characters have to be encoded. For example, if you are searching for SMS sent from the phone number +61437085284, your search query q would be:

  • q=from:%2B61437085284

You can use the URL encoder to encode the text. If a character is not an alphanumeric character (A-Z, a-z, 0-9), it is typically either reserved or unsafe and should be encoded.

order_by
string
Default: "date:asc"

Specifies the field and order to sort the results by. The value is composed of the field name followed by a colon and the sort direction (asc for ascending or desc for descending). The default sort order is by date in ascending order. You can use the following fields:

  • date
  • username
  • from
  • to
  • status
  • body

For example, if you want to order by the most recently sent SMS, you should sort by date in descending order. The query would look like this:

order_by=date:desc

date_from
integer

Start date to filter results. It should be in Unix format.

date_to
integer

End date to filter results. It should be in Unix format.

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
{
  • "status": 200,
  • "response_code": "SUCCESS",
  • "response_msg": "Here are your history.",
  • "data": [
    ]
}

Export SMS History

Use this endpoint to create a download link of your SMS history. You can filter the SMS history result using the query parameters.

Request
query Parameters
filename
string
Default: "export.csv"

The filename of the result. It should be in the .csv format.

page
integer
Default: 1

The page number to retrieve. Use this parameter to navigate through the pagination results. The default value is 1.

Example: page=1
limit
integer [ 15 .. 100 ]
Default: 15

The number of items to return per page. This parameter controls the size of each page of results. The default value is 15.

Example: limit=15
q
string
Default: "field_name"

Allows filtering of results based on your search criteria. The query should be in the format field_name:value.

  1. Field Name: The field within the SMS history you want to filter by. You can use the following fields:

    • Status: The status of the SMS. Available values for status are: Queued, Completed, Scheduled, WaitApproval, Failed, Cancelled, CancelledAfterReview, Received, Sent.

    • To: The recipient of the SMS.

    • from: The sender of the SMS.

    • subaccount_id: The sub-account identifier.

    • message_id: The ID of your SMS.

  2. Value: The text or keyword you're searching for within the specified field. If left empty after the colon, the filter will look for all templates with any value in the Field Name.

For example, if you are searching for a SMS with the status of Scheduled, the final query would look like this:

q=status:Scheduled

Note:

Some characters have to be encoded. For example, if you are searching for SMS sent from the phone number +61437085284, your search query q would be:

  • q=from:%2B61437085284

You can use the URL encoder to encode the text. If a character is not an alphanumeric character (A-Z, a-z, 0-9), it is typically either reserved or unsafe and should be encoded.

order_by
string
Default: "date:asc"

Specifies the field and order to sort the results by. The value is composed of the field name followed by a colon and the sort direction (asc for ascending or desc for descending). The default sort order is by date in ascending order. You can use the following fields:

  • date
  • username
  • from
  • to
  • status
  • body

For example, if you want to order by the most recently sent SMS, you should sort by date in descending order. The query would look like this:

order_by=date:desc

date_from
integer

Start date to filter results. It should be in Unix format.

date_to
integer

End date to filter results. It should be in Unix format.

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
Copyright © ClickSend 2024. All right reserved.