Messaging
/
SMS
/
View SMS History

SMS

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.

Note :

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.
Languages
Servers
https://rest.clicksend.com/

Send SMS

Request

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.

Headers
Content-Typestring
Example: application/json
Bodyapplication/json
sendersArray 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_urlsboolean(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.

You will be able to retrieve the open rates and statistics for the link from this link.

More info about shortening URLs here.

messagesArray of objects

Messages to send to customers.

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'

Responses

Successful response

Bodyapplication/json
http_codestring

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.

Example: 200
response_codestring

The response code of the operation. Visit this page for more information.

Example: "SUCCESS"
response_msgstring

A message describing the outcome of the operation.

Example: "Messages queued for delivery."
dataobject

The parameters related to messages.

Response
application/json
{
  "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
  }
}

Calculate SMS Price

Request

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.

Headers
Content-Typestring
Example: application/json
Bodyapplication/json
sendersArray 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_urlsboolean(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.

You will be able to retrieve the open rates and statistics for the link from this link.

More info about shortening URLs here.

messagesArray of objects

Messages to send to customers.

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'

Responses

Successful response

Bodyapplication/json
http_codestring

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.

Example: 200
response_codestring

The response code of the operation. Visit this page for more information.

Example: "SUCCESS"
response_msgstring

A message describing the outcome of the operation.

Example: "Here is some pricing."
dataobject

The parameters related to the messages price.

Example: {"total_price":0.079,"total_count":1,"queued_count":1,"messages":[{"to":"+123456789","body":"string","from":"+123456788","schedule":"","message_id":"1EF50711-2787-68F4-8223-9F9C4393E380","message_parts":1,"message_price":"0.0792","custom_string":"string","is_shared_system_number":false,"country":"AU","status":"SUCCESS"}],"_currency":{"currency_name_short":"AUD","currency_prefix_d":"$","currency_prefix_c":"c","currency_name_long":"Australian Dollars"},"_summary":{"test_message":"This is a test message from None. We are trialing business text messaging.🚀\n\nwww.example.com","countries":{"AU":{"registration_type":0,"recipient_count":1,"usable_sender_id":true,"selected":true,"name":"Australia","regulation":{"country_user_id":1234567,"sms_registration_type":0,"restricted_sending":false,"trial_sending":0,"regulation_requirements_description":"For sending to Australia, you must generally comply with the following:\n\n • No gambling or betting messages\n • No cryptocurrency messages\n • No messages relating to drugs, cannabis or CBD\n • No adult content, including personal ads, or messages related to sex work or prostitution\n • No personal messaging (commercial/business messaging only)\n","created_at":{"date":"2024-03-14 18:12:22.000000","timezone_type":3,"timezone":"UTC"},"updated_at":{"date":"2024-03-14 18:12:22.000000","timezone_type":3,"timezone":"UTC"}}}}},"blocked_count":0}
Response
application/json
{
  "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
  }
}

Create Test SMS Receipt

Request

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.

Headers
Content-Typestring
Example: application/json
Bodyapplication/json
urlstringrequired

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.

Example: "https://sample_webhook_url.m.pipedream.net/"
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'

Responses

Successful response

Bodyapplication/json
http_codeinteger

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.

Example: 200
response_codestring

The response code of the operation. Visit this page for more information.

Example: "SUCCESS"
response_msgstring

A message describing the outcome of the operation.

Example: "Receipt has been added"
dataobject

The parameters related to the message receipt.

Response
application/json
{
  "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
  }
}

View SMS Receipts

Request

Query
pageinteger

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

Default 1
Example: page=1
limitinteger[ 15 .. 100 ]

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

Default 15
Example: limit=15
Headers
Content-Typestring
Example: application/json
curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \

'https://rest.clicksend.com/v3/sms/receipts'

Responses

Successful response

Bodyapplication/json
http_codeinteger

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.

Example: 200
response_codestring

The response code of the operation. Visit this page for more information.

Example: "SUCCESS"
response_msgstring

A message describing the outcome of the operation.

Example: "Here are your delivery receipts."
dataobject

The parameters related to the total message receipts shown. The response will depend on the pagination parameters, specified in the query parameters.

Example: {"total":1,"per_page":16,"current_page":1,"last_page":1,"next_page_url":null,"prev_page_url":null,"from":1,"to":1,"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}]}
Response
application/json
{
  "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": [ … ]
  }
}

View Specific SMS Receipt

Request

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.

Path
message_idstringrequired

The message_id of the SMS delivery reciept to retrieve

Headers
Content-Typestring
Example: application/json
curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \

'https://rest.clicksend.com/v3/sms/receipts/{message_id}'

Responses

Successful response

Bodyapplication/json
http_codeinteger

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.

Example: 200
response_codestring

The response code of the operation. Visit this page for more information.

Example: "SUCCESS"
response_msgstring

A message describing the outcome of the operation.

Example: "Your receipt."
dataobject(sms_receipt)
Response
application/json
{
  "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
  }
}

Mark SMS Receipt As Read

Request

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

Headers
Content-Typestring
Example: application/json
Bodyapplication/json
date_beforeinteger

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

Example: 1722565660
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'

Responses

Successful response

Bodyapplication/json
http_codeinteger

The HTTP code of the response. Visit this page for more information.

Example: 200
response_codestring

The response code of the operation. Visit this page for more information.

Example: "SUCCESS"
response_msgstring

A message describing the outcome of the operation.

Example: "Receipts have been marked as read."
dataobject or null

The parameters related to the SMS receipt.

Warning:

This parameter is deprecated and will return null.

Example: null
Response
application/json
{
  "http_code": 200,
  "response_code": "SUCCESS",
  "response_msg": "Receipts have been marked as read.",
  "data": null
}

Create Test Inbound SMS

Request

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.

Headers
Content-Typestring
Example: application/json
Bodyapplication/json
urlstringrequired

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.

Example: "https://sample_webhook_url.m.pipedream.net/"
webhook_typestring

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.

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'

Responses

Successful response

Bodyapplication/json
http_codeinteger

The HTTP code of the response. Visit this page for more information.

Example: 200
response_codestring

The response code of the operation. Visit this page for more information.

Example: "SUCCESS"
response_msgstring

A message describing the outcome of the operation.

Example: "Test inbound message has been added."
dataobject(inbound_sms_test)

The parameters related to the message receipt.

Response
application/json
{
  "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"
  }
}

View Inbound SMS

Request

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.

Query
pageinteger

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

Default 1
Example: page=1
limitinteger[ 15 .. 100 ]

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

Default 15
Example: limit=15
Headers
Content-Typestring
Example: application/json
curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \

'https://rest.clicksend.com/v3/sms/inbound'

Responses

Successful response

Bodyapplication/json
http_codeinteger

The HTTP code of the response. Visit this page for more information.

Example: 200
response_codestring

The response code of the operation. Visit this page for more information.

Example: "SUCCESS"
response_msgstring

A message describing the outcome of the operation.

Example: "Here are your data."
dataobject

The parameters related to the total inbound SMS shown. The response will depend on the pagination parameters, specified in the query.

Example: {"total":1,"per_page":15,"current_page":1,"last_page":1,"next_page_url":null,"prev_page_url":null,"from":1,"to":15,"data":[{"timestamp_send":1722997250,"from":"+61123456789","body":"reply to msg on 7 aug 2024","original_body":"test msg","original_message_id":"1EF54639-F16D-681E-947A-4F4FCDFD2B87","to":"+61113456789","custom_string":"","message_id":"D2F2BCC3-6558-4DAA-858E-AD7529CC809C","_keyword":"reply"}]}
Response
application/json
{
  "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": [ … ]
  }
}

View a specific inbound SMS message

Request

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.

Path
original_message_idstringrequired

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.
Headers
Content-Typestring
Example: application/json
curl --location 'https://rest.clicksend.com/v3/sms/inbound/{original_message_id}' \
--header 'Content-Type: application/json' \
--header 'Authorization: API_KEY'

Responses

Successful response

Bodyapplication/json
http_codeinteger

The HTTP code of the response. Visit this page for more information.

Example: 200
response_codestring

The response code of the operation. Visit this page for more information.

Example: "SUCCESS"
response_msgstring

A message describing the outcome of the operation.

Example: "Here are your result."
dataobject(inbound_sms)

The parameters related to the message receipt.

Response
application/json
{
  "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"
  }
}

Mark Inbound SMS as Read

Request

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.

Headers
Content-Typestring
Example: application/json
Bodyapplication/json
date_beforeinteger

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

Example: "1961900166"
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'

Responses

Successful response

Bodyapplication/json
http_codeinteger

The HTTP code of the response. Visit this page for more information.

Example: 200
response_codestring

The response code of the operation. Visit this page for more information.

Example: "SUCCESS"
response_msgstring

A message describing the outcome of the operation.

Example: "Inbound messages have been marked as read."
dataobject or null

The parameters related to the inbound SMS.

Warning:

This parameter is deprecated and will return null.

Example: null
Response
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

Request

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.

Path
message_idstringrequired

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.
Headers
Content-Typestring
Example: application/json
curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \
     --request PUT \
'https://rest.clicksend.com/v3/sms/inbound-read/{message_id}'

Responses

Successful response

Bodyapplication/json
http_codeinteger

The HTTP code of the response. Visit this page for more information.

Example: 200
response_codestring

The response code of the operation. Visit this page for more information.

Example: "SUCCESS"
response_msgstring

A message describing the outcome of the operation.

Example: "Receipt have been marked as read."
datainteger

The number of SMS marked as read.

If you have multiple inbound rules set to POLL, you will receive the inbound message multiple times. Reading it will mark all those messages as read.

Example: 1
Response
application/json
{
  "http_code": 200,
  "response_code": "SUCCESS",
  "response_msg": "Receipt have been marked as read.",
  "data": 1
}

Cancel SMS

Request

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.

Path
message_idstringrequired

The message_id of the scheduled SMS to cancel.

Headers
Content-Typestring
Example: application/json
curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \
     --request PUT \

'https://rest.clicksend.com/v3/sms/{message_id}/cancel'

Responses

Successful response

Bodyapplication/json
http_codestring

The HTTP code of the response. Visit this page for more information.

Example: 200
response_codestring

The response code of the operation. Visit this page for more information.

Example: "SUCCESS"
response_msgstring

A message describing the outcome of the operation.

Example: "Scheduled sms message has been cancelled."
dataobject

The parameters related to the scheduled SMS.

Warning:

This parameter is deprecated and will return null.

Response
application/json
{
  "http_code": 200,
  "response_code": "SUCCESS",
  "response_msg": "Scheduled sms message has been cancelled.",
  "data": null
}

Cancel All SMS

Request

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

Headers
Content-Typestring
Example: application/json
Bodyapplication/json
custom_stringstring

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.

curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \
     --request PUT \

'https://rest.clicksend.com/v3/sms/cancel-all'

Responses

Successful response

Bodyapplication/json
http_codeinteger

The HTTP code of the response. Visit this page for more information.

Example: 200
response_codestring

The response code of the operation. Visit this page for more information.

Example: "SUCCESS"
response_msgstring

A message describing the outcome of the operation.

Example: "2 sms messages have been cancelled."
dataobject

The parameters related to the cancelled scheduled SMS.

Response
application/json
{
  "http_code": 200,
  "response_code": "SUCCESS",
  "response_msg": "2 sms messages have been cancelled.",
  "data": {
    "count": 2
  }
}

View SMS Templates

Request

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

Query
pageinteger

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

Default 1
Example: page=1
limitinteger[ 15 .. 100 ]

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

Default 15
Example: limit=15
qstring

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.

Default "field_name"
order_bystring

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

Default "template_id:asc"
Headers
Content-Typestring
Example: application/json
curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \

'https://rest.clicksend.com/v3/sms/templates'

Responses

Successful response

Bodyapplication/json
http_codeinteger

The HTTP status code of the response.

Example: 200
response_codestring

The response code indicating the status of the operation.

Example: "SUCCESS"
response_msgstring

A message describing the outcome of the operation.

Example: "Here are your templates."
dataobject

The parameters related to the total message receipts shown. The response will depend on the pagination parameters, specified in the query parameters.

Example: [{"totlal":1,"per_page":15,"current_page":1,"last_page":1,"next_page_url":null,"prev_page_url":null,"from":1,"to":1,"data":[{"template_id":587713,"body":"this_is_a_test_template wew21","template_name":"qowiei_1920"}]}]
Response
application/json
{
  "http_code": 200,
  "response_code": "SUCCESS",
  "response_msg": "Here are your templates.",
  "data": [
    { … }
  ]
}

Create SMS Template

Request

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

Headers
Content-Typestring
Example: application/json
Bodyapplication/json
template_namestring

The name of the template.

Example: "Template 501916"
bodystring

body String The main content of your template.

Example: "This is a test template.\r\nnew line 漢字 here."
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'

Responses

Successful response

Bodyapplication/json
http_codestring

The HTTP code of the response. Visit this page for more information.

Example: 200
response_codestring

The response code of the operation. Visit this page for more information.

Example: "SUCCESS"
response_msgstring

A message describing the outcome of the operation.

Example: "New template has been saved."
dataobject(sms_template)

The parameters related to the actual templates.

Response
application/json
{
  "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."
  }
}

View a Specific SMS Template

Request

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

Path
template_idstringrequired

The ID of the template to retrieve

Headers
Content-Typestring
Example: application/json
curl --location --globoff 'https://rest.clicksend.com/v3/sms/templates/{{templateId}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: [API_KEY]'

Responses

Successful response

Bodyapplication/json
http_codestring

The HTTP status code of the response.

Example: 200
response_codestring

The response code indicating the status of the operation.

Example: "SUCCESS"
response_msgstring

A message describing the outcome of the operation.

Example: "Here is your template."
dataobject

The parameters related to the template.

Example: {"template_id":587713,"template_name":"Template 501916","body":"This is a test updated template.\r\nnew line 漢字 here."}
Response
application/json
{
  "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."
  }
}

Update SMS Template

Request

Path
template_idstringrequired

The ID of the template to update.

Headers
Content-Typestring
Example: application/json
Bodyapplication/json
template_namestring

The new name of the template.

Example: "Template XYZ"
bodystring

The new content of your template.

Example: "This is a new update template"
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}'

Responses

Successful response

Bodyapplication/json
http_codestring

The HTTP code of the response. Visit this page for more information.

Example: 200
response_codestring

The response code of the operation. Visit this page for more information.

Example: "SUCCESS"
response_msgstring

A message describing the outcome of the operation.

Example: "Your template has been updated."
dataobject(sms_template_update)

The parameters related to the actual templates.

Response
application/json
{
  "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"
  }
}

Delete SMS Template

Request

Use this endpoint to delete a SMS template. Specify the SMS template to delete by providing its template_id.

Path
template_idstringrequired

The ID of the template to delete.

Headers
Content-Typestring
Example: application/json
curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \
     --request DELETE \

'https://rest.clicksend.com/v3/sms/templates/{template_id}'

Responses

Successful response

Bodyapplication/json
http_codeinteger

The HTTP code of the response. Visit this page for more information

Example: 200
response_codestring

The response code of the operation. Visit this page for more information.

Example: "SUCCESS"
response_msgstring

A message describing the outcome of the operation.

Example: "Your template has been deleted."
dataArray of arrays

The parameters related to the SMS template.

Warning:

This parameter is deprecated and will return null.

Response
application/json
{
  "http_code": 200,
  "response_code": "SUCCESS",
  "response_msg": "Your template has been deleted.",
  "data": null
}

View SMS History

Request

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

Query
pageinteger

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

Default 1
Example: page=1
limitinteger[ 15 .. 100 ]

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

Default 15
Example: limit=15
qstring

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.

Default "field_name"
order_bystring

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

Default "date:asc"
date_frominteger

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

date_tointeger

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

Headers
Content-Typestring
Example: application/json
curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \

'https://rest.clicksend.com/v3/sms/history?date_from=&date_to='

Responses

Successful response

Bodyapplication/json
http_codeinteger

The HTTP code of the response. Visit this page for more information.

Example: 200
response_codestring

The response code of the operation. Visit this page for more information.

Example: "SUCCESS"
response_msgstring

A message describing the outcome of the operation.

Example: "Here are your history."
dataobject

The parameters related to the SMS history shown. The response will depend on the pagination parameters, specified in the query parameters.

Example: [{"direction":"out","date":1715660441,"to":"+61426729707","body":"test message, please ignore","status":"Sent","from":"+61447254068","schedule":"1715660441","status_code":"201","status_text":"Message delivered to the handset","message_id":"1EF11A95-31A2-6B70-A3E2-750B2DF4583F","message_parts":1,"message_price":"0.0792","from_email":null,"list_id":null,"custom_string":null,"contact_id":null,"user_id":496596,"subaccount_id":563840,"country":"AU","carrier":"Vodafone","first_name":null,"last_name":null,"_api_username":"edorlando33@gmail.com"}]
Response
application/json
{
  "status": 200,
  "response_code": "SUCCESS",
  "response_msg": "Here are your history.",
  "data": [
    { … }
  ]
}

Export SMS History

Request

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

Query
filenamestring

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

Default "export.csv"
pageinteger

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

Default 1
Example: page=1
limitinteger[ 15 .. 100 ]

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

Default 15
Example: limit=15
qstring

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.

Default "field_name"
order_bystring

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

Default "date:asc"
date_frominteger

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

date_tointeger

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

Headers
Content-Typestring
Example: application/json
curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \

'https://rest.clicksend.com/v3/sms/history/export?filename={filename}'

Responses

Successful response

Bodyapplication/json
http_codeinteger

The HTTP code of the response. Visit this page for more information.

Example: 200
response_codestring

The response code of the operation. Visit this page for more information.

Example: "SUCCESS"
response_msgstring

A message describing the outcome of the operation.

Example: "Download your file here."
dataobject

The parameters related to the generated SMS history file.

Example: {"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"}
Response
application/json
{
  "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"
  }
}