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.
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.
The senders property specifies sender IDs for each recipient country.
Want to leverage the default sender settings:
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:
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.Join the BETA Program:
Early access to Smart Assign is available. Contact the sales team to opt-in and participate in the BETA program.
This controls whether URLs are automatically shortened. This affects all messages in the request. You can either specify:
You will be able to retrieve the open rates and statistics for the link from this link.
More info about shortening URLs here.
https://rest.clicksend.com/v3/sms/send
curl --include \
--header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \
--request POST \
--header "Content-Type: application/json" \
--data-binary " {
\"messages\":[
{
\"source\":\"php\",
\"body\":\"Jelly liquorice marshmallow candy carrot cake 4Eyffjs1vL.\",
\"to\":\"+61411111111\"
},
{
\"source\":\"php\",
\"body\":\"Chocolate bar icing icing oat cake carrot cake jelly cotton MWEvciEPIr.\",
\"to\":\"+61422222222\"
}
]
}" \
'https://rest.clicksend.com/v3/sms/send'Successful response
The HTTP code of the response. Visit this page for more information.
This parameter doesn’t reflect the status of each message. Check the status parameter of the message object to view the status of the individual message.
The response code of the operation. Visit this page for more information.
A message describing the outcome of the operation.
{ "http_code": 200, "response_code": "SUCCESS", "response_msg": "Messages queued for delivery.", "data": { "total_price": 0.0792, "total_count": 1, "queued_count": 1, "messages": [ … ], "_currency": { … }, "blocked_count": 0 } }
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.
The senders property specifies sender IDs for each recipient country.
Want to leverage the default sender settings:
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:
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.Join the BETA Program:
Early access to Smart Assign is available. Contact the sales team to opt-in and participate in the BETA program.
This controls whether URLs are automatically shortened. This affects all messages in the request. You can either specify:
You will be able to retrieve the open rates and statistics for the link from this link.
More info about shortening URLs here.
https://rest.clicksend.com/v3/sms/price
curl --include \
--header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \
--request POST \
--header "Content-Type: application/json" \
--data-binary " {
\"messages\":[
{
\"source\":\"php\",
\"body\":\"Jelly liquorice marshmallow candy carrot cake 4Eyffjs1vL.\",
\"to\":\"+61411111111\"
},
{
\"source\":\"php\",
\"body\":\"Chocolate bar icing icing oat cake carrot cake jelly cotton MWEvciEPIr.\",
\"to\":"+61422222222"
}
]
}" \
'https://rest.clicksend.com/v3/sms/price'Successful response
The HTTP code of the response. Visit this page for more information.
This parameter doesn’t reflect the status of each message. Check the status parameter of the message object to view the status of the individual message.
The response code of the operation. Visit this page for more information.
A message describing the outcome of the operation.
The parameters related to the messages price.
{ "http_code": 200, "response_code": "SUCCESS", "response_msg": "Here is some pricing.", "data": { "total_price": 0.079, "total_count": 1, "queued_count": 1, "messages": [ … ], "_currency": { … }, "_summary": { … }, "blocked_count": 0 } }
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.
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
You can create a webhook URL in Pipedream to test receiving the SMS receipt. Follow the instructions here.
https://rest.clicksend.com/v3/sms/receipts
curl --include \
--header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \
--request POST \
--header "Content-Type: application/json" \
--data-binary " {
\"url\":\"http://yourdomain.com\"
}" \
'https://rest.clicksend.com/v3/sms/receipts'Successful response
The HTTP code of the response. Visit this page for more information.
This parameter doesn’t reflect the status of each message. Check the status parameter of the message object to view the status of the individual message.
The response code of the operation. Visit this page for more information.
A message describing the outcome of the operation.
{ "http_code": 200, "response_code": "SUCCESS", "response_msg": "Receipt has been added", "data": { "timestamp_send": 1722565411, "timestamp": 1722565411, "message_id": "2336751A-BBBE-4887-9D7C-CB7558F00208", "status_code": "201", "status_text": "Success: Message received on handset.", "error_code": null, "error_text": null, "custom_string": null, "subaccount_id": 563840, "message_type": "sms", "digits": null } }
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.
The page number to retrieve. Use this parameter to navigate through the pagination results. The default value is 1.
https://rest.clicksend.com/v3/sms/receipts
curl --include \
--header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \
'https://rest.clicksend.com/v3/sms/receipts'Successful response
The HTTP code of the response. Visit this page for more information.
This parameter doesn’t reflect the status of each message. Check the status parameter of the message object to view the status of the individual message.
The response code of the operation. Visit this page for more information.
A message describing the outcome of the operation.
The parameters related to the total message receipts shown. The response will depend on the pagination parameters, specified in the query parameters.
{ "http_code": 200, "response_code": "SUCCESS", "response_msg": "Here are your delivery receipts.", "data": { "total": 1, "per_page": 16, "current_page": 1, "last_page": 1, "next_page_url": null, "prev_page_url": null, "from": 1, "to": 1, "data": [ … ] } }
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.
https://rest.clicksend.com/v3/sms/receipts/{message_id}
curl --include \
--header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \
'https://rest.clicksend.com/v3/sms/receipts/{message_id}'Successful response
The HTTP code of the response. Visit this page for more information.
This parameter doesn’t reflect the status of each message. Check the status parameter of the message object to view the status of the individual message.
The response code of the operation. Visit this page for more information.
{ "http_code": 200, "response_code": "SUCCESS", "response_msg": "Your receipt.", "data": { "timestamp_send": 1722565661, "timestamp": 1722565661, "message_id": "D6D16B28-46AC-484A-AB0A-A08CD08EF75C", "status_code": "201", "status_text": "Success: Message received on handset.", "error_code": null, "error_text": null, "custom_string": null, "subaccount_id": 123456, "message_type": "sms", "digits": null } }
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
The cutoff date. Receipts sent before this time will be marked as read. It’s in the Unix format.
https://rest.clicksend.com/v3/sms/receipts-read
curl --include \
--header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \
--request PUT \
--header "Content-Type: application/json" \
--data-binary "{
\"date_before\": 1441958441
}" \
'https://rest.clicksend.com/v3/sms/receipts-read'Successful response
The response code of the operation. Visit this page for more information.
A message describing the outcome of the operation.
{ "http_code": 200, "response_code": "SUCCESS", "response_msg": "Receipts have been marked as read.", "data": null }
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.
The webhook URL where the inbound SMS will be sent to.
You can create a webhook URL in Pipedream to test receiving the inbound SMS. Follow the instructions here.
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.
https://rest.clicksend.com/v3/sms/inbound
curl --include \
--header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \
--request POST \
--header "Content-Type: application/json" \
--data-binary " {
\"url\":\"http://yourdomain.com\"
}" \
'https://rest.clicksend.com/v3/sms/inbound'Successful response
The response code of the operation. Visit this page for more information.
A message describing the outcome of the operation.
{ "http_code": 200, "response_code": "SUCCESS", "response_msg": "Test inbound message has been added.", "data": { "timestamp_send": 1722580202, "from": "+61487722156", "body": "This is a test incoming SMS. E8PWYYVFWK.", "original_body": "This is the original message. LSGRMF3FOW.", "original_message_id": "00DD4A0B-FC0F-4FFB-9A95-4BACC477C372", "to": "+61411111111", "custom_string": "Test custom string ", "message_id": "7E0F75B6-8CE0-4202-B589-8BA8E5CBA661", "_keyword": "this" } }
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.
If you have multiple inbound rules set to POLL, you will receive the inbound message multiple times.
The page number to retrieve. Use this parameter to navigate through the pagination results. The default value is 1.
https://rest.clicksend.com/v3/sms/inbound
curl --include \
--header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \
'https://rest.clicksend.com/v3/sms/inbound'Successful response
The response code of the operation. Visit this page for more information.
The parameters related to the total inbound SMS shown. The response will depend on the pagination parameters, specified in the query.
{ "http_code": 200, "response_code": "SUCCESS", "response_msg": "Here are your data.", "data": { "total": 1, "per_page": 15, "current_page": 1, "last_page": 1, "next_page_url": null, "prev_page_url": null, "from": 1, "to": 15, "data": [ … ] } }
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.
When you receive an inbound message, you will get two parameters: original_message_id and message_id:
https://rest.clicksend.com/v3/sms/inbound/{original_message_id}
curl --location 'https://rest.clicksend.com/v3/sms/inbound/{original_message_id}' \
--header 'Content-Type: application/json' \
--header 'Authorization: API_KEY'Successful response
The response code of the operation. Visit this page for more information.
A message describing the outcome of the operation.
{ "http_code": 200, "response_code": "SUCCESS", "response_msg": "Here are your result.", "data": { "timestamp": 1723012981, "from": "+61426123123", "body": "test", "original_body": "test", "original_message_id": "1EF54878-1137-62F4-9EAC-CBF078A1262E", "to": "+61437085284", "custom_string": "", "message_id": "F892B812-24E3-404B-A1CB-D714BBB2B127", "_keyword": "reply" } }
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.
The cutoff date. Inbound SMS sent before this time will be marked as read. It’s in the Unix format.
https://rest.clicksend.com/v3/sms/inbound-read
curl --include \
--header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \
--request PUT \
--header "Content-Type: application/json" \
--data-binary " {
\"date_before\":1442398100
}" \
'https://rest.clicksend.com/v3/sms/inbound-read'Successful response
The response code of the operation. Visit this page for more information.
A message describing the outcome of the operation.
{ "http_code": 200, "response_code": "SUCCESS", "response_msg": "Inbound messages have been marked as read.", "data": null }
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.
The message_id of the inbound SMS to mark as read.
When you receive an inbound message, you will get two parameters: original_message_id and message_id:
https://rest.clicksend.com/v3/sms/inbound-read/{message_id}
curl --include \
--header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \
--request PUT \
'https://rest.clicksend.com/v3/sms/inbound-read/{message_id}'Successful response
The response code of the operation. Visit this page for more information.
A message describing the outcome of the operation.
{ "http_code": 200, "response_code": "SUCCESS", "response_msg": "Receipt have been marked as read.", "data": 1 }
https://rest.clicksend.com/v3/sms/{message_id}/cancel
curl --include \
--header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \
--request PUT \
'https://rest.clicksend.com/v3/sms/{message_id}/cancel'Successful response
The response code of the operation. Visit this page for more information.
A message describing the outcome of the operation.
{ "http_code": 200, "response_code": "SUCCESS", "response_msg": "Scheduled sms message has been cancelled.", "data": null }
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.
https://rest.clicksend.com/v3/sms/cancel-all
curl --include \
--header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \
--request PUT \
'https://rest.clicksend.com/v3/sms/cancel-all'Successful response
The response code of the operation. Visit this page for more information.
A message describing the outcome of the operation.
{ "http_code": 200, "response_code": "SUCCESS", "response_msg": "2 sms messages have been cancelled.", "data": { "count": 2 } }
Use this endpoint to retrieve SMS templates. You can filter the SMS templates result using the query parameters.
The page number to retrieve. Use this parameter to navigate through the pagination results. The default value is 1.
The number of items to return per page. This parameter controls the size of each page of results. The default value is 15.
Allows filtering of results based on your search criteria. The query should be in the format field_name:value.
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
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:
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.
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:
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
https://rest.clicksend.com/v3/sms/templates
curl --include \
--header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \
'https://rest.clicksend.com/v3/sms/templates'Successful response
A message describing the outcome of the operation.
The parameters related to the total message receipts shown. The response will depend on the pagination parameters, specified in the query parameters.
{ "http_code": 200, "response_code": "SUCCESS", "response_msg": "Here are your templates.", "data": [ { … } ] }
https://rest.clicksend.com/v3/sms/templates
curl --include \
--header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \
--request POST \
--header "Content-Type: application/json" \
--data-binary " {
\"template_name\":\"Template 501916\",
\"body\":\"This is a sample content: H7YI68B3yk for this template.\"
}" \
'https://rest.clicksend.com/v3/sms/templates'Successful response
The response code of the operation. Visit this page for more information.
A message describing the outcome of the operation.
{ "http_code": 200, "response_code": "SUCCESS", "response_msg": "New template has been saved.", "data": { "template_id": 589242, "template_name": "TTemplate 501916", "body": "This is a test template.\r\nnew line 漢字 here." } }
Use this endpoint to retrieve a SMS template. Specify which template to retrieve using the template ID.
https://rest.clicksend.com/v3/sms/templates/{template_id}
curl --location --globoff 'https://rest.clicksend.com/v3/sms/templates/{{templateId}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: [API_KEY]'{ "http_code": 200, "response_code": "SUCCESS", "response_msg": "Here is your template.", "data": { "template_id": 587713, "template_name": "Template 501916", "body": "This is a test updated template.\r\nnew line 漢字 here." } }
Use this endpoint to update a SMS template.
https://rest.clicksend.com/v3/sms/templates/{template_id}
curl --include \
--header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \
--request PUT \
--header "Content-Type: application/json" \
--data-binary " {
\"template_name\":\"I am updated\",
\"body\":\"This is a sample content: Sc0KNWgSMG for this template.\"
}" \
'https://rest.clicksend.com/v3/sms/templates/{template_id}'Successful response
The response code of the operation. Visit this page for more information.
A message describing the outcome of the operation.
{ "http_code": 200, "response_code": "SUCCESS", "response_msg": "Your template has been updated.", "data": { "template_id": 587916, "template_name": "Template XYZ", "body": "This is a new update template" } }
Use this endpoint to delete a SMS template. Specify the SMS template to delete by providing its template_id.
https://rest.clicksend.com/v3/sms/templates/{template_id}
curl --include \
--header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \
--request DELETE \
'https://rest.clicksend.com/v3/sms/templates/{template_id}'Successful response
The response code of the operation. Visit this page for more information.
A message describing the outcome of the operation.
{ "http_code": 200, "response_code": "SUCCESS", "response_msg": "Your template has been deleted.", "data": null }
The page number to retrieve. Use this parameter to navigate through the pagination results. The default value is 1.
The number of items to return per page. This parameter controls the size of each page of results. The default value is 15.
Allows filtering of results based on your search criteria. The query should be in the format field_name:value.
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.
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
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:
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.
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:
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
Start date to filter results. It should be in Unix format.
End date to filter results. It should be in Unix format.
https://rest.clicksend.com/v3/sms/history
curl --include \
--header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \
'https://rest.clicksend.com/v3/sms/history?date_from=&date_to='Successful response
The response code of the operation. Visit this page for more information.
A message describing the outcome of the operation.
The parameters related to the SMS history shown. The response will depend on the pagination parameters, specified in the query parameters.
{ "status": 200, "response_code": "SUCCESS", "response_msg": "Here are your history.", "data": [ { … } ] }
The page number to retrieve. Use this parameter to navigate through the pagination results. The default value is 1.
The number of items to return per page. This parameter controls the size of each page of results. The default value is 15.
Allows filtering of results based on your search criteria. The query should be in the format field_name:value.
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.
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
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:
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.
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:
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
Start date to filter results. It should be in Unix format.
End date to filter results. It should be in Unix format.
https://rest.clicksend.com/v3/sms/history/export
curl --include \
--header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \
'https://rest.clicksend.com/v3/sms/history/export?filename={filename}'Successful response
The response code of the operation. Visit this page for more information.
A message describing the outcome of the operation.
The parameters related to the generated SMS history file.
{ "http_code": 200, "response_code": "SUCCESS", "response_msg": "Download your file here.", "data": { "url": "https://clicksend-api-downloads.s3.ap-southeast-2.amazonaws.com/_private/CF08618C-5E61-4957-914E-3F75E305CB62?response-content-disposition=attachment%3Bfilename%3DSMS_history.csv&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=XXXXXXXXXXXXXXXap-southeast-2%2Fs3%2Faws4_request&X-Amz-Date=20240830T053306Z&X-Amz-SignedHeaders=host&X-Amz-Expires=1200&X-Amz-Signature=82a0e5740550c171c9c90ccf94fc69dbdb34bfc83acee22b8d13d7043994aa62" } }