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. 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
list_id
required
integer

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.

name
required
string

The SMS campaign name.

from
required
string

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.
body
required
string

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.
source
string

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

schedule
integer

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

required
Array 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.

url_to_shorten
string

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

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",
  • "senders": [
    ]
}
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.