Campaign Manager
Introduction
Campaign Manager allows you to send the same SMS to hundreds of thousands of phone numbers within minutes. For more details, please review the general documentation.
This document covers the API(s) that are available to you to manage campaigns and get information on credits added to the account to track the usage of the service.
Campaign
Campaign Status
A campaign can be in one of the following states:
-
Initiating: The Campaign is getting created. For example setting up From numbers, To numbers and Body. Ideally the Campaign will remain in this state for a very short time. If there are any errors in processing
From
orTo
numbers, the Campaign will directly move to aFailed
state. -
Scheduled: The Campaign is Scheduled. This means the Campaign Manager has all the resources and data it needs to execute this Campaign when Scheduled time kicks in. The only option to move Campaign, via API call, from a Scheduled state is to Cancelled state.
-
Cancelled: When a scheduled Campaign is Cancelled.
-
InProgress: The Campaign is in Progress. This state automatically kicks in when scheduled time has arrived. The only possible transition from this state is either
Completed
orFailed
-
Completed: Once all SMS are successfully sent to the underlying platform, the Campaign is marked as completed. It doesn’t depend on the state of SMS, for example whether it is Delivered or not.
-
Failed: If the Campaign failed for some reason or cannot setup data correctly from the initiating state.
The life cycle of Campaign’s Status is as below:

Create Campaign
The Create Campaign API is used to create SMS Campaigns.
Request Parameters
Parameter | Description |
---|---|
body |
Mandatory. The SMS Body. |
name |
Mandatory. The name of the campaign. |
startTime |
Mandatory. Date when Campaign is to be started given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-05). When only a date is provided the time is assumed to be at midnight of the given date. Note: that the given date/time is inclusive and is assumed to be in UTC timezone. |
fromPrefix |
The prefix for country code for source/origin address, Campaign Manager application will automatically generate random source address with specific prefix. |
fromFile |
The source/origin phone address. Multipart File values can be passed as new line separated. In case of multiple values passed, each address will be used as round robin for the given number of |
toFile |
Mandatory. The destination address. Multipart File having multiple |
Response Body
The response body will contain the code, corresponding message, and data of the Application if it was successfully created. HTTP response will be 200 Created(OK).
The response returned is the JSON body as shown in the example below. Parameters are as explained below:
Parameter | Description |
---|---|
data |
Campaign data as explained in the table below. |
code |
Sub-error code for response |
message |
Message describing error if error occured or success message |
Data Parameters
Data Parameter | Description |
---|---|
fromPrefix |
The prefix for country code for source/origin address, campaignmanager application will automatically generate random source address with specific prefix. |
sid |
Unique sid identity for Campaign |
name |
Name of the Campaign |
dateCreated |
Date when Campaign was created given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-05). When only a date is provided the time is assumed to be at midnight of the given date. Note: that the given date/time is inclusive and is assumed to be in UTC timezone. |
dateUpdated |
Date when Campaign was updated given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-05). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone. |
startTime |
Date when Campaign is to be started given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-05). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone. |
enterpriseSid |
The Business Customer sid to which the Campaign belongs. |
total |
The number of SMS segments for this Campaign. |
Status |
The status of the campaign as explained earlier. |
The Create Campaign API can also return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition, seen below are the Errors that it can return.
Error Code | HTTP Status | Error Message | Description | Category |
---|---|---|---|---|
489 |
409 |
Start Time is invalid |
Campaign is defined with a start date in the past. |
Create, Update Campaign |
Example
{ "name" : "TestCampaign", "startTime":"2020-01-01T22:45:32", "fromPrefix":"+91", "toFile":"file:/user/home/toPhoneNumbersfile.txt", "body":"Happy New Year" }
From the bash terminal you can run the command below:
curl -X POST \ https://yourdomain.com/campaignmanager/campaigns \ --user ' {your_account_SID}:{your_account_token}' \ -H 'Cache-Control: no-cache' \ -H 'Content-Type: application/json' \ -d '{ "name" : "TestCampaign", "startTime":"2020-01-01T22:45:32", "fromPrefix":"+91", "toFile":"file:/user/home/toPhoneNumbersfile.txt" "body":"Happy New Year" }’
If creation of campaign is successful, below is the response returned:
{ "data": { "sid": "EC2f1e91bcdeb346519612a96dd31dcd53", "dateUpdated": "2020-01-01T11:40:15+0000", "dateCreated": "2020-01-01T11:40:15+0000", "accountSid": "AC9f5746bbeba827841634b106f23e7395", "accountEmail": "teste1@testent7.com", "uri": "/campaignmanager/campaigns/search/EC2f1e91bcdeb346519612a96dd31dcd53", "name": "Test Data 1", "startTime": "2020-01-01T22:45:32+0000", "enterpriseSid": "ENfda064f487ff4309b8b306d25adc0a86", "total": 1, "status": "initiating", "fromPrefix": "+91" }, "code": 200, "message": "OK" }
Update Campaign
This endpoint will be used to update existing campaigns. Only campaigns with a status of “Scheduled” can be updated. If the status of the campaign changes to any other, updating is no longer possible.
Request Parameters
Parameter | Description |
---|---|
status |
The status of the campaign can be changed from Scheduled to Cancelled. |
CampaignSid |
Unique Campaign SID of the campaign |
Response Body
The Response Body will carry Code, corresponding message and data of Application if it was successfully Updated. HTTP response will be 200 OK.
The response returned is JSON body as shown in the example below. Parameters are as explained below.
Parameter | Description |
---|---|
data |
Campaign data as explained in the data parameter of create campaign. |
code |
Sub-error code for response |
message |
Message describing error if error occured or success message |
Update Campaign API can also return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition, seen below are the Errors that it can return.
Error Code | HTTP Status | Error Message | Description | Category |
---|---|---|---|---|
485 |
409 |
Campaign Status is mandatory |
Status of campaign missing while updating campaign |
Update Campaign |
489 |
409 |
Start Time is invalid |
Campaign is defined with a start date in the past. |
Create Campaign, Update Campaign |
486 |
409 |
Enterprise campaign not found |
Campaign SID doesn’t exist in the system or probably assigned to some other Organization where existing user doesn’t have permission to access. |
Update Campaign, Delete Campaign, List Single Campaign |
487 |
409 |
Enterprise Campaign cannot update status |
Enterprise Campaign cannot update status |
Update Campaign |
Example
{
"status" : "cancelled"
}
From the bash terminal you can run the command below:
curl -X PUT \
https://yourdomain.com/campaignmanager/campaigns/CPb6eb071d21124dbab20b095c25f1274f \
--user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
"status" : "cancelled"
}’
If update of Context is successful, below is the response returned:
{
"data": {
"sid": "EC2f1e91bcdeb346519612a96dd31dcd53",
"dateUpdated": "2020-01-01T11:40:15+0000",
"dateCreated": "2020-01-01T11:40:15+0000",
"accountSid": "AC9f5746bbeba827841634b106f23e7395",
"accountEmail": "teste1@testent7.com",
"uri": "/campaignmanager/campaigns/search/EC2f1e91bcdeb346519612a96dd31dcd53",
"name": "Test Data 1",
"startTime": "2020-01-01T22:45:32+0000",
"enterpriseSid": "ENfda064f487ff4309b8b306d25adc0a86",
"total": 1,
"status": "cancelled",
"fromPrefix": "+91"
},
"code": 200,
"message": "OK"
}
If update of Context fails, corresponding error code and message is returned along with HTTP Error Response
{
"errorCode": "486",
"message": "Enterprise campaign not found",
"data": {
"sid": "EC2f1e91bcdeb346519612a96dd31dcd"
}
}
Delete Campaign
This endpoint will be used to delete existing campaigns. Only campaigns with a status of Scheduled can be deleted. If the status of the campaign changes to any other, deleting is no longer possible.
Response Body
The Response Body will carry Code, corresponding message and data of Application if it was successfully Updated. HTTP response will be 200 OK.
The response returned is JSON body as shown in the example below. Parameters are as explained below.
Parameter | Description |
---|---|
data |
Campaign data as explained in the data parameter of create campaign. |
code |
Sub-error code for response |
message |
Message describing error if error occured or success message |
Delete Campaign API can also return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition, seen below are the Errors that it can return.
Error Code | HTTP Status | Error Message | Description | Category |
---|---|---|---|---|
488 |
409 |
Enterprise Campaign cannot be deleted |
Enterprise Campaign cannot be deleted as status not scheduled |
Delete Campaign |
486 |
409 |
Enterprise campaign not found |
Campaign SID doesn’t exist in the system or probably assigned to some other Organization where existing user doesn’t have permission to access. |
Update Campaign, Delete Campaign, List Single Campaign |
Example
From the bash terminal you can run the command below:
curl -X DELETE \
https://yourdomain.com/campaignmanager/campaigns/CPb6eb071d21124dbab20b095c25f1274f \
--user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json'
If delete of Campaign is successful, below is the response returned:
{
"data": {
"sid": "EC2f1e91bcdeb346519612a96dd31dcd53",
"dateUpdated": "2020-01-01T11:40:15+0000",
"dateCreated": "2020-01-01T11:40:15+0000",
"accountSid": "AC9f5746bbeba827841634b106f23e7395",
"accountEmail": "teste1@testent7.com",
"uri": "/campaignmanager/campaigns/search/EC2f1e91bcdeb346519612a96dd31dcd53",
"name": "Test Data 1",
"startTime": "2020-01-01T22:45:32+0000",
"enterpriseSid": "ENfda064f487ff4309b8b306d25adc0a86",
"total": 1,
"status": "cancelled",
"fromPrefix": "+91"
},
"code": 200,
"message": "OK"
}
Get List of Campaigns
This endpoint will be used to retrieve a list of existing campaigns.
Paging
The following paging parameters are supported
Query Parameter | Description |
---|---|
pageSize |
Number of records returned per page |
page |
Which page of Campaigns records to return, starting from 0. |
If the search API is called without page and pageSize, by default pageSize will be 10 and page will be 0 to avoid retrieving all data in a single API call. |
Filtering
Following filtering parameters are supported:
Query Parameter | Description |
---|---|
endTime |
Optional parameter. Only show Contexts that were created on this date/time or earlier, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-06T02:10:03) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-06). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone. |
name |
Optional parameter. Only show Campaign’s that match name text, partially or fully. |
status |
Optional parameter. Only show campaigns having selected status. Possible value of status are as explained in campaign status section. |
startTime |
Optional parameter. Only show Contexts that were created on this date/time or later, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-05). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone. |
Sorting Information
You can use the SortBy GET query parameter to determine which attribute you want to sort by and in which direction; direction can either be 'asc' for ascending and 'desc' for descending sort ordering. Here’s the overall format: SortBy=<sorting attribute>:<direction>. If no direction parameter is provided, then the listing of calls is sorted by the attribute in ascending order. ou can sort by the following attributes:
Response Parameters
Response Body will carry Code, corresponding message, and data of Campaigns if it was successfully fetched. HTTP response will be 200 OK.
The response returned is JSON body as shown in the example below. Parameters are as explained below.
Code | Description |
---|---|
data |
data of search as explained in Data parameters below |
code |
Sub-error code for response |
message |
Message describing error if error occured or success message |
Data parameters
Data Parameter | Description |
---|---|
uri |
Unique URI that you can call to get records |
result |
campaign data as explained in Data Parameter of create campaign |
pageSize |
Number of records returned per page. |
total |
Total Number of records |
page |
Which page of records to return. |
numPages |
Total number of pages |
start |
Starting offset of page |
end |
Ending offset of page |
firstPageUri |
Unique URI that you can call to get records in First page |
nextPageUri |
Unique URI that you can call to get records in next page |
Example
From the bash terminal you can run the command below:
curl -X GET \ https://yourdomain.com/campaignmanager/campaigns/search?name=test \ --user ' {your_account_SID}:{your_account_token}' \ -H 'Cache-Control: no-cache' \ -H 'Content-Type: application/json'
Below is the response returned:
{ "data": { "result": [ { "sid": "EC2f1e91bcdeb346519612a96dd31dcd53", "dateUpdated": "2020-01-01T11:40:15+0000", "dateCreated": "2020-01-01T11:40:15+0000", "accountSid": "AC9f5746bbeba827841634b106f23e7395", "accountEmail": "teste1@testent7.com", "uri": "/campaignmanager/campaigns/search/EC2f1e91bcdeb346519612a96dd31dcd53", "name": "Test Data 1", "startTime": "2020-01-01T22:45:32+0000", "enterpriseSid": "ENfda064f487ff4309b8b306d25adc0a86", "total": 1, "status": "cancelled", "fromPrefix": "+91" }, ], "pageSize": 10, "total": 1, "page": 0, "numPages": 1, "start": 0, "end": 0, "firstPageUri": "/campaignmanager/campaigns/search/?pageSize=10&page=0", "uri": "/campaignmanager/campaigns/search/?pageSize=10&page=0" }, "code": 200, "message": "OK" }
Get Single Campaign
The Single Campaign search API allows users to retrieve specific Campaigns.
Response Parameters
Response Body will carry Code, corresponding message, and data of User if it was successfully searched. HTTP response will be 200 OK.
The response returned is JSON body as shown in the example below. Parameters are as explained below.
Parameter | Description |
---|---|
data |
Campaign data as explained in the data parameter of create campaign. |
code |
Sub-error code for response |
message |
Message describing error if error occured or success message |
Delete Campaign API can also return Error Code and corresponding HTTP Error as mentioned in Common Response Error Code. In addition, seen below are the Errors that it can return.
Error Code | HTTP Status | Error Message | Description | Category |
---|---|---|---|---|
486 |
409 |
Enterprise campaign not found |
Campaign SID doesn’t exist in the system or probably assigned to some other Organization where existing user doesn’t have permission to access. |
Update Campaign, Delete Campaign, List Single Campaign |
Example
From the bash terminal you can run the command below:
curl -X DELETE \
https://yourdomain.com/campaignmanager/campaigns/search/CPb6eb071d21124dbab20b095c25f1274f \
--user ' {your_account_SID}:{your_account_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
Below is the response returned:
{
"data": {
"sid": "EC2f1e91bcdeb346519612a96dd31dcd53",
"dateUpdated": "2020-01-01T11:40:15+0000",
"dateCreated": "2020-01-01T11:40:15+0000",
"accountSid": "AC9f5746bbeba827841634b106f23e7395",
"accountEmail": "teste1@testent7.com",
"uri": "/campaignmanager/campaigns/search/EC2f1e91bcdeb346519612a96dd31dcd53",
"name": "Test Data 1",
"startTime": "2020-01-01T22:45:32+0000",
"enterpriseSid": "ENfda064f487ff4309b8b306d25adc0a86",
"total": 1,
"status": "cancelled",
"fromPrefix": "+91"
},
"code": 200,
"message": "OK"
}
Credit
Get List of Credits
This endpoint will be used to get list of Credits for the Business Customer.
Paging
The following paging parameters are supported.
Query Parameter | Description |
---|---|
pageSize |
Number of records returned per page |
page |
Which page of Participants records to return, starting from 0. |
If the search API is called without page and pageSize, by default pageSize will be 10 and page will be 0 to avoid retrieving all data in a single API call. |
Filtering
The following filtering parameters are supported:
Query Parameter | Description |
---|---|
endTime |
Optional parameter. Only show Credits that were created on this date/time or earlier, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-06T02:10:03) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-06). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone. |
type |
Optional parameter. Only show Credits that are either |
startTime |
Optional parameter. Only show Credits that were created on this date/time or later, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-05). When only a date is provided the time is assumed to be at midnight of the given date. Note: that the given date/time is inclusive and is assumed to be in UTC timezone. |
Sorting Information
You can use the SortBy GET query parameter to determine which attribute you want to sort by and in which direction; direction can either be 'asc' for ascending and 'desc' for descending sort ordering. Here’s the overall format: SortBy=<sorting attribute>:<direction>. If no direction parameter is provided, then the listing of calls is sorted by the attribute in ascending order. You can sort by the following attributes:
Parameter | Description |
---|---|
dateCreated |
Sort by created date |
Response Body
The Response Body will carry Code, corresponding message and data of the Credit if it was successfully fetched. HTTP response will be 200 OK.
The response returned is the JSON body as shown in the example below. Parameters are as explained below:
Data Parameter | Description |
---|---|
data |
Actual data in form of a list that matches the filter criteria. Data as explained in Data Parameter in create Credit. |
pageSize |
Number of records returned per page. |
total |
Total Number of records |
page |
Which page of records to return. |
numPages |
Total number of pages |
start |
Starting offset of page |
end |
Ending offset of page |
firstPageUri |
Unique URI that you can call to get records in First page |
nextPageUri |
Unique URI that you can call to get records in next page |
uri |
Unique URI that you can call to get records |
Example
From the bash terminal you can run the command below:
curl -X GET \https://yourdomain.com/campaignmanager/credits/search?enterprriseSid=EN6c9dfebda23b403a959a99112437e785 \ --user ' {your_account_SID}:{your_account_token}' \ -H 'Cache-Control: no-cache' \ -H 'Content-Type: application/json'
Below is the response returned:
{ "data": { "result": [ { "sid": "ENCd05ad50a49e445f5a4924f9862a5a6aa", "dateUpdated": "2020-09-04T07:57:44+0000", "dateCreated": "2020-09-04T07:57:44+0000", "accountSid": "ACb06dc1c0b555df46a02ccaea1cb11bc1", "accountEmail": "cspadmin1@nmorgtest1.com", "uri": "/campaignmanager/credits/ENCd05ad50a49e445f5a4924f9862a5a6aa", "description": "initial credits on 4th", "enterpriseSid": "ENc165d92e63f14fdf84666a9b8a57c805", "credit": 500 } ], "pageSize": 10, "total": 1, "page": 0, "numPages": 1, "start": 0, "end": 0, "firstPageUri": "/campaignmanager/credits/search/?enterpriseSid=ENc165d92e63f14fdf84666a9b8a57c805&pageSize=10&page=0", "uri": "/campaignmanager/credits/search/?enterpriseSid=ENc165d92e63f14fdf84666a9b8a57c805&pageSize=10&page=0" }, "code": 200, "message": "OK" }
Get Single Credit
The Single Credit search API allows users to retrieve a specific Credit.
Response Body
The Response Body will carry the Code, corresponding message, and data of the Credit if it was successfully searched. HTTP response will be 200 OK.
Error Code | HTTP Status | Error Message | Description | Category |
---|---|---|---|---|
472 |
409 |
Credit not found |
Credit SID doesn’t exist in the system |
Get Credit |
The response returned is the JSON body as shown in the example below. Parameters are listed below.
Parameter | Description |
---|---|
data |
Credit data as explained in the Data Parameter of Create Credit. |
code |
Sub-error code for response |
message |
Message describing error if error occurred or success message |
Example
From the bash terminal you can run the command below:
curl -X GET \ https://yourdomain.com/campaignmanager/credits/search/ENCee320039e3e647eaa7df7cef5e3d6b55 \ --user ' {your_account_SID}:{your_account_token}' \ -H 'Cache-Control: no-cache' \ -H 'Content-Type: application/json' \
Below is the response returned:
{ "data": { "sid": "ENC3807ff7ff73e46e7a9c9a95af3d85189", "dateUpdated": "2020-09-04T09:58:57+0000", "dateCreated": "2020-09-04T09:58:57+0000", "accountSid": ACb06dc1c0b555df46a02ccaea1cb11bc1", "accountEmail": "cspadmin1@nmorgtest1.com", "uri": "/campaignmanager/credits/ENC3807ff7ff73e46e7a9c9a95af3d85189", "description": "initial credits", "enterpriseSid": "EN671a5f2c6c5c4e88b814bdc23ca389bc", "credit": 500 }, "code": 200, "message": "OK" }