×
POST

https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/message-campaigns

  • Replace <your_api_key> and <your_api_token> with the API key and token created by you.
  • Replace <your_sid> with your “Account sid”
  • Replace <subdomain> with the region of your account
    1. <subdomain> of Singapore cluster is @api.exotel.com
    2. <subdomain> of Mumbai cluster is @api.in.exotel.com

<your_api_key> , <your_api_token> and <your_sid> are available in the API settings page of your Exotel Dashboard

The following are the POST parameters:

Parameter Name   Mandatory/Optional Value

name

optional

It's an optional parameter in the request. It is used to define the name of the campaign. It should be greater than 3 characters and if not passed, its default value will be created using the 'AccountSID CurrentDate CurrentTime' and passed in the response.

Example: exotel 2021-06-04 11:11:10

content_type

Mandatory

dynamic or static

choose static, if you want to use the same sms body for all the audience.

choose dynamic, if you want to personalized sms based on the data provided in the list
lists Mandatory

Array of listSid, if content_type=static. Up to 5 listSid can be part of one single campaign. 

Single listsid, if content_type=dynamic
channel Mandatory

SMS
schedule Optional

Determines when to start and end a campaign in RFC 3339 date-time

  • start_time - Time when the campaign should start. start_time should be atleast 10 mins ahead of current time.  
  • end_time - Time when the campaign should end even if all sms are not attempted as part of the campaign. There has to be min 2 hours gap between start_time and end_time. 

dlt_entity_id

Mandatory

Numeric Value

dlt_template_id

Mandatory

Numeric Value ( Provide DLT approved Template ID)

sender_id

Mandatory

Alphabetical string ( tansactional)

Numeric ( Promotional )

sms_type

Mandatory

Transactional/Promotional

template

Mandatory

Body of the Sms (Max 2000 char)

Please provide DLT approved SMS template. Replace the variable with @column_header. For example: let's assume the template is " Hi %var, your account is activated" and you want to replace the variable with First_Name ( which is a column name in the list). You can replace the variable by prefix @ @before the Column name like- "Hi @@First_name, your account is activated". Make sure that the variable name should be exactly the same with the column header. You can replace up to 5 variables.

status_callback

optional

Valid http/https url at the campaign level

When a SMS campaign will start or completed, an HTTP POST will be made to the provided URL with the following four parameters:

  • campaign_sid-an alpha-numeric unique identifier of this campaign
  • date_created- ime when the campaign was created
  • date_updated-  time when the campaign was updated
  • status- one of in-progress OR completed 
  • reports- link to the campaign reports ( null when the status is not completed)

sms_status_callback

optional

Valid http/https url at the sms level

Once SMS reaches terminal state (sent/failed/failed_dnd),  an HTTP POST will be made to the provided URL with the following four parameters:

  • campaign_sid - an alpha-numeric unique identifier of this campaign
  • sms_sid - an alpha-numeric unique identifier of this call
  • date_created - time when the resource was created
  • date_sent - time when the resource was updated
  • number - number to which the SMS was made
  • status -submitted, sent/ failed, Failed_Expired 
 
curl --location --request POST 'https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/message-campaigns'  
--header 'Content-Type: application/json'  
--data-raw '{ "name": "CampaignABC",
 "content_type": "static",
 "lists": [ "9120d5962d214316b7721de55bb82e03" ],
 "schedule": 
{"start_time": "2022-01-13T13:13:00+05:30", 
"end_time": "2022-01-13T13:16:00+05:30"
 }, 
"dlt_template_id": "1107160086562376233", 
"dlt_entity_id": "1101428740000012125",
 "sender_id": "EXOTEL", 
"channel": "SMS",
"sms_type": "transactional",
 "template": "Prepaid rental charges for the billing cycle starting
 today have been deducted from your Exotel account. 
Your Exotel account balance is now Rs.100. Thank you.", 
"status_callback": "https://webhook.site/9402df04-f971-4a07-9992-27dc042b1c72" 
}'
var request = require('request');

var options = {

'method': 'POST',

'url': 'https://api.exotel.com/v2/accounts/Exotel/message-campaigns',

'headers': {

'Content-Type': 'application/json',

},

body: JSON.stringify({

"smscampaigns": {

"name": "CampaignABC",

"content_type": "static",

"lists": [

"9120d5962d214316b7721de55bb82e03"

],

"schedule": {

"start_time": "2022-01-13T13:13:00+05:30",

"end_time": "2022-01-13T13:16:00+05:30"

},

"dlt_template_id": "1107160086562376233",

"dlt_entity_id": "1101428740000012125",

"sender_id": "EXOTEL",

"channel": "SMS",

"sms_type": "transactional",

"template": "Prepaid rental charges for the billing cycle starting today have been deducted from your Exotel account. Your Exotel account balance is now Rs.100. Thank you.",

"status_callback": "https://webhook.site/9402df04-f971-4a07-9992-27dc042b1c72"

}

})




};

request(options, function (error, response) {

if (error) thrownewError(error);

console.log(response.body);

});



<?php

$curl = curl_init();

curl_setopt_array($curl, array(

CURLOPT_URL => 'https://api.exotel.com/v2/accounts/Exotel/message-campaigns',

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 =>' {

"smscampaigns": {

"name": "CampaignABC",

"content_type": "static",

"lists":[

"9120d5962d214316b7721de55bb82e03"

],

"schedule": {

"start_time": "2022-01-13T13:13:00+05:30",

"end_time": "2022-01-13T13:16:00+05:30"

},

"dlt_template_id" : "1107160086562376233",

"dlt_entity_id" : "1101428740000012125",

"sender_id" : "EXOTEL",

"channel": "SMS",

"sms_type": "transactional",

"template" : "Prepaid rental charges for the billing cycle starting today have been deducted from your Exotel account. Your Exotel account balance is now Rs.100. Thank you.",

"status_callback" : "https://webhook.site/9402df04-f971-4a07-9992-27dc042b1c72"

}

}

',

CURLOPT_HTTPHEADER => array(

'Content-Type: application/json',

),

));




$response = curl_exec($curl);




curl_close($curl);

echo $response;
import requests

import json

url = "https://api.exotel.com/v2/accounts/Exotel/message-campaigns"

payload = json.dumps({

"smscampaigns": {

"name": "CampaignABC",

"content_type": "static",

"lists": [

"9120d5962d214316b7721de55bb82e03"

],

"schedule": {

"start_time": "2022-01-13T13:13:00+05:30",

"end_time": "2022-01-13T13:16:00+05:30"

},

"dlt_template_id": "1107160086562376233",

"dlt_entity_id": "1101428740000012125",

"sender_id": "EXOTEL",

"channel": "SMS",
"sms_type": "transactional",

"template": "Prepaid rental charges for the billing cycle starting today have been deducted from your Exotel account. Your Exotel account balance is now Rs.100. Thank you.",

"status_callback": "https://webhook.site/9402df04-f971-4a07-9992-27dc042b1c72"

}

})

headers = {

'Content-Type': 'application/json',

}




response = requests.request("POST", url, headers=headers, data=payload)




print(response.text)



package main

import (

"fmt"

"strings"

"net/http"

"io/ioutil"

)




func main() {




url := "https://api.exotel.com/v2/accounts/Exotel/message-campaigns"

method := "POST"




payload := strings.NewReader(` {

"smscampaigns": {

"name": "CampaignABC",

"content_type": "static",

"lists":[

"9120d5962d214316b7721de55bb82e03"

],

"schedule": {

"start_time": "2022-01-13T13:13:00+05:30",

"end_time": "2022-01-13T13:16:00+05:30"

},

"dlt_template_id" : "1107160086562376233",

"dlt_entity_id" : "1101428740000012125",

"sender_id" : "EXOTEL",

"channel": "SMS",

"sms_type": "transactional",

"template" : "Prepaid rental charges for the billing cycle starting today have been deducted from your Exotel account. Your Exotel account balance is now Rs.100. Thank you.",

"status_callback" : "https://webhook.site/9402df04-f971-4a07-9992-27dc042b1c72"

}

}

`)




client := &http.Client {

}

req, err := http.NewRequest(method, url, payload)




if err != nil {

fmt.Println(err)

return

}

req.Header.Add("Content-Type", "application/json")

req.Header.Add("Authorization", "your token")




res, err := client.Do(req)

if err != nil {

fmt.Println(err)

return

}

defer res.Body.Close()




body, err := ioutil.ReadAll(res.Body)

if err != nil {

fmt.Println(err)

return

}

fmt.Println(string(body))

}
  • Example Response
{
"request_id":"745d624f47004b71bf72e6cb7d58a25b",
"method":"POST",
"http_code":200,
"response":[
{
"code":200,
"error_data":null,
"status":"success",
"data":{
"name":"test_campaign",
"content_type":"static",
"sid":"909d2a2ba53ce07f3784668b938eb44914bo",
"account_sid":"<your_sid>",
"lists":[
"68f443cd3e764ad1ae7d82ad27f0af72"
],
"schedule":{
"start_time":"2019-01-20T21:15:00+05:30",
"expiry_time":"2019-01-20T21:16:00+05:30"
},
"status_callback":"https://mycallback.sampledomain.in/1gvta9f1",
"date_created":"2019-01-20T21:10:00+05:30",
"date_updated":"2019-01-20T21:10:00+05:30",
"status":"scheduled",
“report_url”: null,
“dlt_entity_id”: “123478”,
“dlt_template_id”: “098765432”,
“sender_id”: “ADFGH”,
"channel": "SMS",
“sms_type”: “transactional”,
“template”: “Hi, your account is activated”.
}
}
]
}

HTTP Response:

  • On success, the HTTP response status code will be 200
  • The id is the unique identifier of the campaign, and it will be useful to log this for future debugging
  • HTTP body will contain an JSON similar to the one below