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.
Successful response
{- "messages": [
- {
- "body": "string",
- "to": "string",
- "from": "string",
- "source": "string",
- "schedule": 0,
- "custom_string": "string",
- "list_id": "string",
- "contact_id": 0,
- "country": "string",
- "from_email": "string",
- "exclude_no_sender_id_recipients": true
}
]
}
{- "http_code": 200,
- "response_code": "SUCCESS",
- "response_msg": "Messages queued for delivery.",
- "data": {
- "total_price": 0.0792,
- "total_count": 1,
- "queued_count": 1,
- "messages": [
- {
- "direction": "out",
- "date": "1721099039,",
- "to": "+61411111111",
- "body": "test message",
- "from": "+61431111112",
- "schedule": 1721099039,
- "message_id": "1ABC3200-C38C-6308-BE4B-C7C51D01DCF0",
- "message_parts": 1,
- "message_price": 0.0792,
- "from_email": null,
- "list_id": null,
- "custom_string": "",
- "contact_id": null,
- "user_id": 123456,
- "subaccount_id": 123456,
- "is_shared_system_number": false,
- "country": "AU",
- "carrier": "Vodafone",
- "status": "SUCCESS"
}
], - "_currency": {
- "currency_name_short": "AUD",
- "currency_prefix_d": "$",
- "currency_prefix_c": "c",
- "currency_name_long": "Australian Dollars"
}, - "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.
Successful response
{- "messages": [
- {
- "source": "string",
- "to": "1234567",
- "from": "",
- "body": "string",
- "custom_string": "string"
}
]
}
{- "http_code": 200,
- "response_code": "SUCCESS",
- "response_msg": "Here is some pricing.",
- "data": {
- "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
}
}
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.
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 Note:You can create a webhook URL in Pipedream to test receiving the SMS receipt. Follow the instructions here. |
Successful response
{
}
{- "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.
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 |
Successful response
curl --include \ --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \ 'https://rest.clicksend.com/v3/sms/receipts'
{- "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": [
- {
- "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 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.
Successful response
curl --include \ --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \ 'https://rest.clicksend.com/v3/sms/receipts/{message_id}'
{- "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
date_before | integer The cutoff date. Receipts sent before this time will be marked as read. It’s in the Unix format. |
Successful response
{- "date_before": 1722565660
}
{- "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.
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:
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. |
Successful response
{
}
{- "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.
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 |
Successful response
curl --include \ --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \ 'https://rest.clicksend.com/v3/sms/inbound'
{- "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": [
- {
- "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"
}
]
}
}
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.
Successful response
curl --location 'https://rest.clicksend.com/v3/sms/inbound/{original_message_id}' \ --header 'Content-Type: application/json' \ --header 'Authorization: API_KEY'
{- "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.
date_before | integer The cutoff date. Inbound SMS sent before this time will be marked as read. It’s in the Unix format. |
Successful response
{- "date_before": "1961900166"
}
{- "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.
Successful response
curl --include \ --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \ --request PUT \ 'https://rest.clicksend.com/v3/sms/inbound-read/{message_id}'
{- "http_code": 200,
- "response_code": "SUCCESS",
- "response_msg": "Receipt have been marked as read.",
- "data": 1
}
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.
Successful response
curl --include \ --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \ --request PUT \ 'https://rest.clicksend.com/v3/sms/{message_id}/cancel'
{- "http_code": 200,
- "response_code": "SUCCESS",
- "response_msg": "Scheduled sms message has been cancelled.",
- "data": null
}
Use this endpoint to cancel all scheduled SMS. To cancel only one scheduled SMS, use the Cancel SMS endpoint.
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. |
Successful response
{- "custom_string": "string"
}
{- "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.
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
For example, if you are searching for the template with the name of sample_name, the final query would look like this: 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:
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:
For example, if you want to order by the template_id in descending order, the query would look like this: |
Successful response
curl --include \ --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \ 'https://rest.clicksend.com/v3/sms/templates'
{- "http_code": 200,
- "response_code": "SUCCESS",
- "response_msg": "Here are your templates.",
- "data": [
- {
- "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"
}
]
}
]
}
Use this endpoint to create a SMS template that you can use for sending SMS.
Successful response
{- "template_name": "Template 501916",
- "body": "This is a test template.\r\nnew line 漢字 here."
}
{- "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.
Successful response
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.
Successful response
{- "template_name": "Template XYZ",
- "body": "This is a new update template"
}
{- "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.
Successful response
curl --include \ --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \ --request DELETE \ 'https://rest.clicksend.com/v3/sms/templates/{template_id}'
{- "http_code": 200,
- "response_code": "SUCCESS",
- "response_msg": "Your template has been deleted.",
- "data": null
}
Use this endpoint to view previously sent SMS. You can filter the SMS history result using the 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
For example, if you are searching for a SMS with the status of Scheduled, the final query would look like this: 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:
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:
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: |
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. |
Successful response
curl --include \ --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \ 'https://rest.clicksend.com/v3/sms/history?date_from=&date_to='
{- "status": 200,
- "response_code": "SUCCESS",
- "response_msg": "Here are your history.",
- "data": [
- {
- "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"
}
]
}
Use this endpoint to create a download link of your SMS history. You can filter the SMS history result using the 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
For example, if you are searching for a SMS with the status of Scheduled, the final query would look like this: 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:
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:
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: |
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. |
Successful response
curl --include \ --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \ 'https://rest.clicksend.com/v3/sms/history/export?filename={filename}'
{- "http_code": 200,
- "response_code": "SUCCESS",
- "response_msg": "Download your file here.",
}