Campaign
The Campaign APIs allow you to create, manage, and send message campaigns to all contacts within a specified phonebook.
Send a campaign
This endpoint allows you to send campaigns to all contacts within a specified phonebook.
By default, the Generic (non-DND) route is recommended for sending promotional or marketing campaigns. However, if you wish to send campaigns via the DND (Transactional) route, your Sender ID must be whitelisted for DND messaging. To request Sender ID whitelisting, please contact our support team.
Important: Promotional messages sent through the generic route are subject to time restrictions in Nigeria, telecom operators do not allow delivery between 8:00 PM and 8:00 AM.
Endpoint :
https://BASE_URL/api/sms/campaigns/send
Request Type : POST
Options | Required | Description |
---|---|---|
api_key | yes | string Your API key (It can be found on your Termii dashboard). |
country_code | yes | string Represents short numeric geographical codes developed to represent countries ( Example: 234 ) . |
sender_id | yes | string Represents the ID of the sender which can be alphanumeric or numeric. Alphanumeric sender ID length should be between 3 and 11 characters (Example: CompanyName ) |
message | yes | string Text of a message that would be sent to the destination phone number |
channel | yes | string This is the route through which the message is sent. It is either dnd , or generic |
message_type | yes | string The type of message that is sent, which is a plain or unicode. |
phonebook_id | yes | string The unique ID of the phonebook you want to send the campaign message to. |
enable_link_tracking | no | boolean Set to true to enable link tracking, allowing the system to track and record link clicks. Set to false to disable link tracking |
campaign_type | yes | string Represents type of campaign which can either be personalized or regular |
schedule_sms_status | yes | string To send a scheduled campaign, pass scheduled as the value or pass regular if you are sending a campaign that should not be scheduled |
schedule_time | no | string The time to send scheduled campaign. This is required if scheduled_sms_status is scheduled |
{
"api_key":"Your API KEY",
"country_code":"234",
"sender_id" : "Termii",
"message":"Welcome to Termii.",
"channel": "generic",
"message_type": "Plain",
"phonebook_id": "2d9f4a02-85b8-45e5-9f5b-30f93ef472e2",
"delimiter":",",
"remove_duplicate":"yes",
"enable_link_tracking": true ,
"campaign_type":"personalized",
"schedule_time":"30-06-2021 6:00",
"schedule_sms_status":"scheduled"
}
var data = {
"api_key":"Your API KEY",
"country_code":"234",
"sender_id" : "Termii",
"message":"Welcome to Termii.",
"channel": "generic",
"message_type": "Plain",
"phonebook_id": "2d9f4a02-85b8-45e5-9f5b-30f93ef472e2",
"delimiter":",",
"remove_duplicate":"yes",
"enable_link_tracking": true,
"campaign_type":"personalized",
"schedule_time":"30-06-2021 6:00",
"schedule_sms_status":"scheduled"
};
var data = JSON.stringify(data);
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function() {
if(this.readyState === 4) {
console.log(this.responseText);
}
});
xhr.open("POST", " https://BASE_URL/api/sms/campaigns/send");
xhr.setRequestHeader("Content-Type", "application/json");
xhr.setRequestHeader("Content-Type", "application/json");
xhr.send(data);
var request = require('request');
var data = {
"api_key":"TLtX0534XcuIpjfghpD8qOIKezptPlEAQoipJdcz
2omiPwtQ6g2YypJEO570jg'",
"country_code":"234",
"sender_id" : "Termii",
"message":"Welcome to Termii.",
"channel": "generic",
"message_type": "Plain",
"phonebook_id": "2d9f4a02-85b8-45e5-9f5b-30f93ef472e2",
"delimiter":",",
"remove_duplicate":"yes",
"enable_link_tracking": true,
"campaign_type":"personalized",
"schedule_time":"30-06-2021 6:00",
"schedule_sms_status":"scheduled"
};
var options = {
'method': 'POST',
'url': ' https://BASE_URL/api/sms/campaigns/send',
'headers': {
'Content-Type': ['application/json', 'application/json']
},
body: JSON.stringify(data)
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
import requests
url = " https://BASE_URL/api/sms/campaigns/send"
payload = {
"api_key":"Your API KEY",
"country_code":"234",
"sender_id" : "Termii",
"message":"Welcome to Termii.",
"channel": "generic",
"message_type": "Plain",
"phonebook_id": "2d9f4a02-85b8-45e5-9f5b-30f93ef472e2",
"delimiter":",",
"remove_duplicate":"yes",
"enable_link_tracking": true,
"campaign_type":"personalized",
"schedule_time":"30-06-2021 6:00",
"schedule_sms_status":"scheduled"
}
headers = {
'Content-Type': 'application/json',
}
response = requests.request("POST", url, headers=headers, json=payload)
print(response.text)
RestClient restClient = new RestClient(" https://BASE_URL/api/sms/campaigns/send");
//Creating Json object
JObject objectBody = new JObject();
objectBody.Add("api_key","Your API Key");
objectBody.Add("country_code", "234");
objectBody.Add( "sender_id", "Termii");
objectBody.Add( "message", "Welcome to Termii.");
objectBody.Add( "channel", "generic");
objectBody.Add( "message_type", "plain");
objectBody.Add( "phonebook_id", "2d9f4a02-85b8-45e5-9f5b-30f93ef472e2");
objectBody.Add( "delimiter", ",");
objectBody.Add( "remove_duplicate", "yes");
objectBody.add( "enable_link_tracking", true);
objectBody.Add( "campaign_type","personalized");
objectBody.Add( "schedule_time","30-06-2021 6:00");
objectBody.Add("schedule_sms_status":, "scheduled");
RestRequest restRequest = new RestRequest(Method.POST);
restRequest.AddHeader("Content-Type", "application/json");
restRequest.AddParameter("application/json", objectBody, ParameterType.RequestBody);
IRestResponse restResponse = restClient.Execute(restRequest);
Console.WriteLine(restResponse.Content);
Unirest.setTimeouts(0, 0);
HttpResponse<String> response = Unirest.post("https://BASE_URL/api/sms/campaigns/send")
.header("Content-Type", "application/json")
.body("{\r\n \"api_key\": \"Your API Key\",\r\n \"phone_book\": \"Phone Test \",\r\n \"description\": \"Phonebook for test\"\r\n }")
.asString();
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://BASE_URL/api/sms/campaigns/send',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS =>'
{
"api_key":"Your API KEY",
"country_code":"234",
"sender_id" : "Termii",
"message":"Welcome to Termii.",
"channel": "generic",
"message_type": "Plain",
"phonebook_id": "2d9f4a02-85b8-45e5-9f5b-30f93ef472e2",
"delimiter":",",
"remove_duplicate":"yes",
"enable_link_tracking": true,
"campaign_type":"personalized",
"schedule_time":"30-06-2021 6:00",
"schedule_sms_status":"scheduled"
}
',
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
Sample Response - 201 OK
{
"message": "Your campaign has been scheduled",
"campaignId": "C714360330258",
"status": "success"
}
Fetch campaigns
This endpoint retrieves a list of all campaigns that have been sent from your account.
Endpoint :
https://BASE_URL/api/sms/campaigns?api_key=Your API KEY
Request Type : GET
Sample Response - 200 OK
{
"content": [
{
"campaign_id": "C714360330258",
"run_at": "07-08-2025 13:00",
"status": "DELIVERED",
"created_at": 1754568051635,
"phone_book": "12 contacts",
"camp_type": "regular",
"total_recipients": 12
},
{
"campaign_id": "C883996058770",
"run_at": "07-08-2025 12:59",
"status": "DELIVERED",
"created_at": 1754567988893,
"phone_book": "12 contacts",
"camp_type": "regular",
"total_recipients": 12
},
{
"campaign_id": "C466506364089",
"run_at": "07-08-2025 12:58",
"status": "DELIVERED",
"created_at": 1754567924377,
"phone_book": "12 contacts",
"camp_type": "regular",
"total_recipients": 12
},
{
"campaign_id": "C745756456563",
"run_at": "01-08-2025 16:39",
"status": "DELIVERED",
"created_at": 1754062786066,
"phone_book": "Greatness",
"camp_type": "regular",
"total_recipients": 3
},
{
"campaign_id": "C266806497506",
"run_at": "30-07-2025 19:46",
"status": "DELIVERED",
"created_at": 1753901164394,
"phone_book": "Greatness",
"camp_type": "regular",
"total_recipients": 3
},
{
"campaign_id": "C321543704177",
"run_at": "30-07-2025 19:44",
"status": "DELIVERED",
"created_at": 1753901051224,
"phone_book": "Greatness",
"camp_type": "regular",
"total_recipients": 3
},
{
"campaign_id": "C116316661276",
"run_at": "18-07-2025 11:49",
"status": "DELIVERED",
"created_at": 1752835794928,
"phone_book": "Greatness",
"camp_type": "regular",
"total_recipients": 3
},
{
"campaign_id": "C598979514827",
"run_at": "18-07-2025 11:44",
"status": "DELIVERED",
"created_at": 1752835479308,
"phone_book": "Greatness",
"camp_type": "regular",
"total_recipients": 3
},
{
"campaign_id": "C956871030794",
"run_at": "18-07-2025 11:42",
"status": "DELIVERED",
"created_at": 1752835327117,
"phone_book": "Greatness",
"camp_type": "regular",
"total_recipients": 3
},
{
"campaign_id": "C822393175309",
"run_at": "18-07-2025 11:38",
"status": "DELIVERED",
"created_at": 1752835084708,
"phone_book": "Greatness",
"camp_type": "regular",
"total_recipients": 3
},
{
"campaign_id": "C854227300109",
"run_at": "10-07-2025 14:33",
"status": "FAILED",
"created_at": 1752154432019,
"phone_book": "Greatness",
"camp_type": "regular",
"total_recipients": 3
},
{
"campaign_id": "C612203424163",
"run_at": "02-07-2025 15:56",
"status": "DELIVERED",
"created_at": 1751468164352,
"phone_book": "Greatness",
"camp_type": "regular",
"total_recipients": 3
},
{
"campaign_id": "C737982444011",
"run_at": "30-06-2025 14:23",
"status": "DELIVERED",
"created_at": 1751289817995,
"phone_book": "Greatness",
"camp_type": "regular",
"total_recipients": 3
},
{
"campaign_id": "C005507576663",
"run_at": "20-06-2025 11:55",
"status": "DELIVERED",
"created_at": 1750416912859,
"phone_book": "Greatness",
"camp_type": "regular",
"total_recipients": 3
},
{
"campaign_id": "C738030617458",
"run_at": "20-06-2025 10:56",
"status": "DELIVERED",
"created_at": 1750413378838,
"phone_book": "Greatness",
"camp_type": "regular",
"total_recipients": 3
}
],
"pageable": {
"sort": {
"empty": false,
"sorted": true,
"unsorted": false
},
"offset": 0,
"pageNumber": 0,
"pageSize": 15,
"paged": true,
"unpaged": false
},
"totalPages": 10,
"totalElements": 149,
"last": false,
"sort": {
"empty": false,
"sorted": true,
"unsorted": false
},
"size": 15,
"number": 0,
"first": true,
"numberOfElements": 15,
"empty": false
}
Fetch campaign history
This endpoint retrieves the details of a specific campaign previously sent from your account.
Endpoint :
https://BASE_URL/api/sms/campaigns/campaign_id?api_key=Your API KEY
Request Type : GET
Sample Response - 200 OK
{
"id": "688a686cbf5cd77880287d35",
"applicationId": 33217,
"uuid": "4950076e-dd66-4792-ba65-78c80f250bac",
"createdAt": "30-07-2025 18:46",
"updatedAt": "30-07-2025 18:46",
"campaignId": "C266806497506",
"phonebookId": "67921db0a6c2f16317365fe0",
"phonebookName": "Greatness",
"sender": "Great",
"message": "Hello,\n\n\nNice to meet you. Please click this link: https://app.termii.com/\n\n\nBye.",
"countryCode": "234",
"smsType": "plain",
"campaignType": "regular",
"status": "DELIVERED",
"cost": 18.0000,
"totalRecipient": 3,
"totalDelivered": 0,
"totalFailed": 0,
"sent": 3,
"runAt": "30-07-2025 19:46",
"isLinkTrackingEnabled": true,
"rerun": false,
"sendBy": "sender",
"personalized": false
}
Retry campaign
This endpoint allows you to retry a failed campaign.
Endpoint :
https://BASE_URL/api/sms/campaigns/{{campaign_id}}
Request Type : PATCH
Body params
Options | Required | Description |
---|---|---|
api_key | yes | string Your API key (It can be found on your Termii dashboard. |
Sample Response - 200 OK
{
"message": "Your failed campaign has been retried",
"status": "success"
}