You can use the SMS campaign endpoints to send an SMS campaign, check the cost of sending an SMS campaign, view SMS campaign history, and cancel a scheduled SMS campaign. Add these endpoints as part of your workflow.
Relevant guides: SMS campaign analytics, Can we shorten a URL manually?, and How to send a SMS campaign?.
You can post to a list with up to 20000 recipients with each API call. You can only send to a single list containing up to 20,000 recipients. The response is far less detailed than the normal Send SMS endpoint. Use the SMS Send endpoint if you would like to send to less than 1000 recipients at once. You are required to add an opt-out message to the end of your message body if you are sending marketing message. This can be in the form of asking users to reply STOP to opt-out or by including StopMsg.me/xxxxx which is a placeholder that will add a link that can be clicked to out-out. Refer to Status Codes for definitions of HTTP status code responses.
The list_id of the contact list to send the message to. Use the View Contact List endpoint to see your contact lists. You can also use the other list endpoints to create and manage your contact list. You need to provide the to parameter or the list_id parameter.
The sender of the message. This is also referred to as the Sender ID. You can use:
The message to send. The price of sending a message depends on the number of characters and the type of message. There are two types:
The source of the request. For example, the name of your application. It's used to identify messages sent from various applications.
The time you want the message to be sent. It should be in Unix format.
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.
The sender ID must be either an alpha tag or a phone number. It is a required field unless the sender type is a shared_longcode.
If the sender ID is an alpha tag, it must be between 3 and 11 characters long and contains only letters, numbers, and pluses.
The type of sender ID, it only supports shared_longcode at the moment.
The ISO 3166-1 alpha-2 country code that identifies the country associated with the sender’s number in a shared pool. This is affected only when sender_type is set to shared_longcode to determine the appropriate number based on the sender’s geographic location. If this field is not provided or left empty, it will default to the recipient's country code.
curl --include \
--header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \
--request POST \
--header "Content-Type: application/json" \
--data-binary "{
\"list_id\":428,
\"name\":\"My Campaign 1\",
\"body\":\"This is my new campaign message.\"
}" \
'https://rest.clicksend.com/v3/sms-campaigns/send'{ "http_code": 200, "response_code": "SUCCESS", "response_msg": "Your new campaign has been added.", "data": { "sms_campaign_id": 7, "name": "My Campaign 1", "user_id": 1, "subaccount_id": 1, "list_id": 428, "from": "+61353787448", "body": "This is my new campaign message. StopMsg.me/xxxxx", "schedule": "1444821615", "status": "Queued", "date_added": "1444962630", "custom_string": null, "url_to_shorten": "string", "unsubscribe_link": 0, "source": null, "senders": [ … ], "_total_count": 10, "_list_name": "string" } }
Calculate price for sms campaign
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| list_id | integer(int32) | true | none | Your list id. |
| name | string | true | none | Your campaign name. |
| body | string | true | none | Your campaign message. |
| from | string | true | yes | Your sender id |
| schedule | integer(int32) | false | none | Your schedule timestamp. |
Refer to Status Codes for definitions of HTTP status code responses.
curl --include \
--header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \
--request POST \
--header "Content-Type: application/json" \
--data-binary "{
\"list_id\":428,
\"name\":\"My Campaign 1\",
\"body\":\"(First Name), this is your new campaign message.\"
}" \
'https://rest.clicksend.com/v3/sms-campaigns/price'{ "http_code": 200, "response_code": "SUCCESS", "response_msg": "Here is your price for your SMS Campaign.", "data": { "total_count": 1, "total_price": "0.035", "data": { … }, "_currency": { … } } }
Update sms campaign
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| sms_campaign_id | path | integer(int32) | true | ID of SMS campaign to update |
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| list_id | integer(int32) | true | none | Your list id. |
| name | string | true | none | Your campaign name. |
| body | string | true | none | Your campaign message. |
| from | string | true | yes | Your sender id |
| schedule | integer(int32) | false | none | Your schedule timestamp. |
Refer to Status Codes for definitions of HTTP status code responses.
curl --include \
--header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \
--request PUT \
--header "Content-Type: application/json" \
--data-binary "{
\"list_id\":428,
\"name\":\"Awesome campaign.\",
\"body\":\"his is an awesome message.\"
}" \
'https://rest.clicksend.com/v3/sms-campaigns/{sms_campaign_id}'{ "http_code": 200, "response_code": "SUCCESS", "response_msg": "Your SMS Campaign has been updated.", "data": { "sms_campaign_id": 7, "name": "My Campaign 1", "user_id": 1, "subaccount_id": 1, "list_id": 428, "from": "+61353787448", "body": "This is my new campaign message. StopMsg.me/xxxxx", "schedule": "1444821615", "status": "Queued", "date_added": "1444962630", "custom_string": null, "url_to_shorten": "string", "unsubscribe_link": 0, "source": null, "senders": [ … ], "_total_count": 10, "_list_name": "string" } }
curl --include \
--header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \
'https://rest.clicksend.com/v3/sms-campaigns/{sms_campaign_id}'Successful response
The response code of the operation. Visit Visit this page for more information.
{ "http_code": 200, "response_code": "SUCCESS", "response_msg": "Your SMS Campaign.", "data": { "sms_campaign_id": 7, "name": "My Campaign 1", "user_id": 1, "subaccount_id": 1, "list_id": 428, "from": "+61353787448", "body": "This is my new campaign message. StopMsg.me/xxxxx", "schedule": "1444821615", "status": "Queued", "date_added": "1444962630", "custom_string": null, "url_to_shorten": "string", "unsubscribe_link": 0, "source": null, "senders": [ … ], "_total_count": 10, "_list_name": "string" } }
curl --include \
--header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \
--request PUT \
'https://rest.clicksend.com/v3/sms-campaigns/{sms_campaign_id}/cancel'Successful response
The response code of the operation. Visit this page for more information.
{ "http_code": 200, "response_code": "SUCCESS", "response_msg": "Your SMS Campaign.", "data": { "sms_campaign_id": 2135501, "name": "kkde", "user_id": 496596, "subaccount_id": 563840, "list_id": 2484219, "from": "edwardo3312", "body": "new message2👍👎 smsu.io/xxxxx Reply STOP to opt-out ", "schedule": 2147483647, "status": "Scheduled", "date_added": 1726199079, "custom_string": "testz1", "url_to_shorten": "https://developers.clicksend.com/docs/", "unsubscribe_link": 0, "source": "new_soruce", "senders": [ … ], "_total_count": 5, "_list_name": "Opt-Out List" } }
The page number to retrieve. Use this parameter to navigate through the [pagination]/#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 campaign you want to filter by. You can use the following fields:
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 campaign 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_added in ascending order. You can use the following fields:
For example, if you want to order by the most recently sent or scheduled SMS, you should sort by date in descending order. The query would look like this:
order_by=schedule:desc
You can also sort by these fields:
Start date to filter results. It should be in Unix format.
End date to filter results. It should be in Unix format.
curl --include \
--header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \
'https://rest.clicksend.com/v3/sms-campaigns'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 total SMS campaign shown. The response will depend on the query parameters.
{ "http_code": 200, "response_code": "SUCCESS", "response_msg": "Here are your SMS campaign(s) (shared included).", "data": { "total": 1, "per_page": 15, "current_page": 1, "last_page": 1, "next_page_url": null, "prev_page_url": null, "from": 1, "to": 1, "data": [ … ] } }