SMS Campaigns (1.0.0)

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

Send SMS Campaign

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.

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...
Request
header Parameters
Content-Type
string
Example: application/json
Request Body schema: application/json
object
Responses
200

Successful response

post/v3/sms-campaigns/send
Request samples
application/json
{
  • "list_id": "{{listId}}",
  • "name": "My Campaign",
  • "from": "+6141111111",
  • "body": "Hey (First Name), I want to ask if this is your lastname: (Last Name)? Visit http://smsg.io/xxxxx for more details.",
  • "url_to_shorten": "http://www.google.com/",
  • "subject": "New sms campaign test"
}
Response samples
application/json
{
  • "http_code": 200,
  • "response_code": "SUCCESS",
  • "response_msg": "Your new campaign has been added.",
  • "data": {
    }
}

Calculate SMS Campaign Price

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...
Request
header Parameters
Content-Type
string
Example: application/json
Request Body schema: application/json
object
Responses
200

Successful response

post/v3/sms-campaigns/price
Request samples
application/json
{
  • "list_id": "{{listId}}",
  • "name": "My Campaign",
  • "from": "+61411111111",
  • "body": "Hey (First Name), I want to ask if this is your lastname: (Last Name)?"
}
Response samples
application/json
{
  • "http_code": 200,
  • "response_code": "SUCCESS",
  • "response_msg": "Here is your price for your SMS Campaign.",
  • "data": {
    }
}

Update SMS Campaign

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...
Request
path Parameters
sms_campaign_id
required
string
header Parameters
Content-Type
string
Example: application/json
Request Body schema: application/json
object
Responses
200

Successful response

put/v3/sms-campaigns/{sms_campaign_id}
Request samples
application/json
{
  • "list_id": "{{listId}}",
  • "name": "My Campaign2",
  • "from": "+61411111111",
  • "body": "Hey (First Name), I want to ask if this is your lastname: (Last Name)?"
}
Response samples
application/json
{
  • "http_code": 200,
  • "response_code": "SUCCESS",
  • "response_msg": "Your SMS Campaign has been updated.",
  • "data": {
    }
}

View Specific SMS Campaign

Use this endpoint to view a specific SMS campaign.

Request
path Parameters
sms_campaign_id
required
string

ID of SMS campaign to get

header Parameters
Content-Type
string
Example: application/json
Responses
200

Successful response

get/v3/sms-campaigns/{sms_campaign_id}
Request samples 
curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \

'https://rest.clicksend.com/v3/sms-campaigns/{sms_campaign_id}'
Response samples
application/json
{
  • "http_code": 200,
  • "response_code": "SUCCESS",
  • "response_msg": "Your SMS Campaign.",
  • "data": {
    }
}

Cancel SMS Campaign

Use this endpoint to cancel a scheduled SMS campaign.

Request
path Parameters
sms_campaign_id
required
string

ID of the scheduled SMS campaign to cancel.

header Parameters
Content-Type
string
Example: application/json
Responses
200

Successful response

put/v3/sms-campaigns/{sms_campaign_id}/cancel
Request samples 
curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \
     --request PUT \

'https://rest.clicksend.com/v3/sms-campaigns/{sms_campaign_id}/cancel'
Response samples
application/json
{
  • "http_code": 200,
  • "response_code": "SUCCESS",
  • "response_msg": "Your SMS Campaign.",
  • "data": {
    }
}

View SMS Campaigns

Use this endpoint to view SMS campaigns.

Request
query Parameters
page
integer
Default: 1

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

q
string

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

  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 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_by
string

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

header Parameters
Content-Type
string
Example: application/json
Responses
200

Successful response

get/v3/sms-campaigns
Request samples 
curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \

'https://rest.clicksend.com/v3/sms-campaigns'
Response samples
application/json
{
  • "http_code": 200,
  • "response_code": "SUCCESS",
  • "response_msg": "Here are your SMS campaign(s) (shared included).",
  • "data": {
    }
}
Copyright © ClickSend 2024. All right reserved.