Messaging

Calculate SMS Campaign Price

SMS Campaigns

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?.

Download OpenAPI description

sms-campaigns.json

sms-campaigns.yaml

Servers

https://rest.clicksend.com/

Send SMS Campaign

Request

SMS Campaign Endpoint

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.

This endpoint requires authentication,more info...

Security

basicAuth

Headers

Content-Typestring

Example: application/json

Bodyapplication/json

list_idintegerrequired

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.

Example: "{{listId}}"

namestringrequired

The SMS campaign name.

Example: "My Campaign"

fromstringrequired

The sender of the message. This is also referred to as the Sender ID. You can use:

Shared number: A number that is randomly selected from a pool if no number is specified. This is not available in the US and Canada. You can’t use a shared number if you have a dedicated number.
Dedicated number: A number you've purchased from ClickSend. You can purchase a dedicated number using the Dashboard or the Purchase Dedicated Number endpoint. It should be in the international format (E.164).
Alpha tag: A sender name, like the name of your business, used as the Sender ID instead of a number. Recipients cannot reply to an alpha tag. You can register an alpha tag using the dashboard or the Request Alpha Tag endpoint. Check which countries support alpha tags here.
Own number: Your own number that is connected to your account. Replies from recipients are sent directly to your number. You can register your own number using the dashboard or the Request Own Number Verification OTP endpoint to get the verification_id and OTP code needed for the Verify Own Number OTP endpoint. This isn't available in the US and Canada. If your Sender ID has a different country code to the recipient’s, it'll be replaced by a local number, except in certain countries. If the sender number is blocked, a different number will replace it.

Example: "+6141111111"

bodystringrequired

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:

Standard message - Contains only characters in the GSM set, with a maximum of 160 characters.
Unicode message - Contains characters outside the GSM set, with a maximum of 70 characters.
Longer messages will be sent as multiple messages (parts), but the recipient will receive them as a single long message. Visit this page to learn more about the number of characters per message, and this page to count the number of characters.

Example: "Hey (First Name), I want to ask if this is your lastname: (Last Name)? Visit http://smsg.io/xxxxx for more details."

sourcestring

The source of the request. For example, the name of your application. It's used to identify messages sent from various applications.

scheduleinteger

The time you want the message to be sent. It should be in Unix format.

sendersArray of objects(senders)required

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.

senders[].recipient_country_codestringrequired

Recipient ISO country code

senders[].sender_idstring

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.

senders[].sender_typestring

The type of sender ID, it only supports shared_longcode at the moment.

Value"shared_longcode"

senders[].sender_country_codestring

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.

url_to_shortenstring

The URL you want to shorten. The shortened URL will be appended to the end of the message body.

Example: "http://www.google.com/"

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'

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: "Your new campaign has been added."

dataobject(sms_campaign)

The parameters related to the SMS campaign.

Response

application/json

{
  "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 SMS Campaign Price

Request

Calculate price for sms campaign

Properties

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.

This endpoint requires authentication,more info...

Security

basicAuth

Headers

Content-Typestring

Example: application/json

Bodyapplication/json

list_idstring

Example: "{{listId}}"

namestring

Example: "My Campaign"

fromstring

Example: "+61411111111"

bodystring

Example: "Hey (First Name), I want to ask if this is your lastname: (Last Name)?"

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'

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 is your price for your SMS Campaign."

dataobject

Response

application/json

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

Request

Update sms campaign

Parameters

Parameter	In	Type	Required	Description
sms_campaign_id	path	integer(int32)	true	ID of SMS campaign to update

Properties

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.

This endpoint requires authentication,more info...

Security

basicAuth

Path

sms_campaign_idstringrequired

Headers

Content-Typestring

Example: application/json

Bodyapplication/json

list_idstring

Example: "{{listId}}"

namestring

Example: "My Campaign2"

fromstring

Example: "+61411111111"

bodystring

Example: "Hey (First Name), I want to ask if this is your lastname: (Last Name)?"

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}'

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: "Your SMS Campaign has been updated."

dataobject(sms_campaign)

The parameters related to the SMS campaign.

Response

application/json

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

View Specific SMS Campaign

Request

Use this endpoint to view a specific SMS campaign.

Security

basicAuth

Path

sms_campaign_idstringrequired

ID of SMS campaign to get

Headers

Content-Typestring

Example: application/json

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

'https://rest.clicksend.com/v3/sms-campaigns/{sms_campaign_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 Visit this page for more information.

Example: "SUCCESS"

response_msgstring

A message describing the outcome of the operation.

Example: "Your SMS Campaign."

dataobject(sms_campaign)

The parameters related to the SMS campaign.

Response

application/json

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

Cancel SMS Campaign

Request

Use this endpoint to cancel a scheduled SMS campaign.

Security

basicAuth

Path

sms_campaign_idstringrequired

ID of the scheduled SMS campaign to cancel.

Headers

Content-Typestring

Example: application/json

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

'https://rest.clicksend.com/v3/sms-campaigns/{sms_campaign_id}/cancel'

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 SMS Campaign."

dataobject(sms_campaign)

The parameters related to the SMS campaign.

Response

application/json

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

View SMS Campaigns

Request

Use this endpoint to view SMS campaigns.

Security

basicAuth

Query

pageinteger

The page number to retrieve. Use this parameter to navigate through the [pagination]/#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

qstring

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:
- sms_campaign_id,name,user_id,subaccount_id,list_id,from,body,schedule,status,date_added,custom_string,url_to_shorten,unsubscribe_link,source
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

Note:

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

q=from:%2B61437085284

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

order_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_added in ascending order. You can use the following fields:

name: The name of the SMS campaign.
status: The status of the SMS campaign.
schedule: The schedule send date of the SMS campaign in the Unix format.
from: The sender of the SMS campaign.
date_added: This is the date you created or updated the SMS campaign in the Unix format.

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

Note:

You can also sort by these fields:

sms_campaign_id,user_id,subaccount_id,list_id,body,custom_string,url_to_shorten,unsubscribe_link, and source.

But this is less common in practice.

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-campaigns'

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 SMS campaign(s) (shared included)."

dataobject

The parameters related to the total SMS campaign shown. The response will depend on the query parameters.

Example: {"total":1,"per_page":15,"current_page":1,"last_page":1,"next_page_url":null,"prev_page_url":null,"from":1,"to":1,"data":[{"sms_campaign_id":2145880,"name":"taz","user_id":496596,"subaccount_id":563840,"list_id":2760107,"from":"+61428584957","body":"Hey (First Name), I want to ask if this is your lastname: (Last Name)?","schedule":1925594636,"status":"Scheduled","date_added":1726466470,"custom_string":"custom_name","url_to_shorten":"","unsubscribe_link":0,"source":"sample_soruce","senders":[{"sender_id":"+12124567890","recipient_country_code":"US"},{"sender_type":"shared_longcode","sender_country_code":"FR","recipient_country_code":"BG"}],"_total_count":1,"_list_name":"frrfe"}]}

Response

application/json

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

SMS Campaigns

Send SMS Campaign

Request

SMS Campaign Endpoint

Responses

Was this helpful?

Calculate SMS Campaign Price

Request

Properties

Responses

Was this helpful?

Update SMS Campaign

Request

Parameters

Properties

Responses

Was this helpful?

View Specific SMS Campaign

Request

Responses

Was this helpful?

Cancel SMS Campaign

Request

Responses

Was this helpful?

View SMS Campaigns

Request

Note:

Note:

Responses

Was this helpful?

SMS Campaigns

Send SMS Campaign

RequestExpand all

SMS Campaign Endpoint

Responses

Was this helpful?

Calculate SMS Campaign Price

Request

Properties

Responses

Was this helpful?

Update SMS Campaign

Request

Parameters

Properties

Responses

Was this helpful?

View Specific SMS Campaign

Request

Responses

Was this helpful?

Cancel SMS Campaign

Request

Responses

Was this helpful?

View SMS Campaigns

Request

Note:

Note:

Responses

Was this helpful?

Request