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

OptionsRequiredDescription
api_keyyesstring
Your API key (It can be found on your Termii dashboard).
country_codeyesstring
Represents short numeric geographical codes developed to represent countries (Example: 234 ) .
sender_idyesstring
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)
messageyesstring
Text of a message that would be sent to the destination phone number
channelyesstring
This is the route through which the message is sent. It is either dnd, or generic
message_typeyesstring
The type of message that is sent, which is a plain or unicode.
phonebook_idyesstring
The unique ID of the phonebook you want to send the campaign message to.
enable_link_trackingnoboolean
Set to true to enable link tracking, allowing the system to track and record link clicks. Set to false to disable link tracking
campaign_typeyesstring
Represents type of campaign which can either be personalized or regular
schedule_sms_statusyesstring
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_timenostring
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

OptionsRequiredDescription
api_keyyesstring
Your API key (It can be found on your Termii dashboard.

Sample Response - 200 OK

{
  "message": "Your failed campaign has been retried",
  "status": "success"
}

Updated at, Thursday, September 11, 2025