BULKSMS

API

Documentation

Created By: Netcore Solutions Pvt. Ltd ©

 BulkSMS API Documentation

CONTENTS
Introduction 4
1.1 Purpose 4
1.2 Audience 4
1.3 Acronyms and Abbreviations 4
1.4 Contact Details 5

Chapter 2 6
2.1 Chapter Overview 6
2.2 Mobile number guidelines in API usage 6
2.3 Choice between IP address & mobile number authentication 6
2.3.1 White listing client public IP addresses – 6
2.3.2 Mobile number & password authentication. 6
2.4 SMS Header and Footer 7
2.5 API in Asynchronous mode 7
2.6 Message Types 8
2.7 How to send UDH (port based) Message 9
2.7.1 UDH Octet parameter details 10
2.7.2 Send Message to a port number with more than 140 bytes, 11
2.7.3 How to encode Binary message 12
2.8 API Parameters 12
2.9 API Responses 14
2.10 Single Message API 19
2.10.1 Using GET method 19
2.10.2 Using POST method 20

2
 BulkSMS API Documentation

2.11 CSV Message API 21

2.11.1 [POST] CSV uploads using ‘filestring’ parameter 22
2.11.2 [GET] CSV uploads using ‘filestring’ parameter 22
2.11.3 [Post] CSV uploads in the file format 23
2.12 XML Message API 23
2.12.1 Special characters conversion 25
2.12.2 DTD for input XML 25
2.12.3 DTD for output XML 33
2.13.4 Using GET method 34
2.14 JSON Message API 35
2.14.1 JSON Single Message API 36
2.14.2 Bulk JSON API 37
2.15 Error Responses 38
2.16 Using HTTPS for APIs 42

Chapter 3 44

3.1 Methods to Fetch Delivery reports 44

3.1.1 Reports VIA Bizbond Panel: 44
3.1.2 Delivery Reports VIA API 45
3.1.3 Delivery Reports VIA Ping Back 47
3.1.4 Delivery reports Via FTP/SFTP upload 49

3.2 Delivery status description:- 49

3
 BulkSMS API Documentation

Introduction
1.1 Purpose
● This document provides a description of the Bulk push API usage for end-users .
● This document also describes the API for collecting delivery reports as well.

1.2 Audience
Enterprises who wish to integrate existing software systems with netcore’s BulkSMS API

1.3 Acronyms and Abbreviations

The acronyms and abbreviations expanded in Table 1-2 are fundamental to the information in this
document.
Table 1-2: Acronyms and abbreviations used in this document

Acronym Explanation

API Application Programming Interface

CSV Comma Separated Values

SMS Short Messaging Service

HTTP Hyper text transfer protocol

HTTPS Hyper text Transfer protocol Secure

IP Internet Protocol

4
 BulkSMS API Documentation

1.4 Contact Details

For any queries related to this document please write to us at [email protected],.

5
 BulkSMS API Documentation

Chapter 2
2.1 Chapter Overview
This chapter contains an overview of nectore’s BulkSMS API.

2.2 Mobile number guidelines in API usage

● For GSM & CDMA messaging, the Receiver Phone Number must start with country code - e.g. 91 in case of an Indian
number.
● No leading ‗0‘ or ‗+‘ are allowed—e.g., the number, 99860XXXXX, should be specified as 9199860XXXXX. This means the
number should always be prefixed by 91 with no leading ‗+‘ or 0‘s.
● For sending message internationally the mobile number should be prefixed with ‘00’ the appropriate country code,
followed by the mobile number. For all local Indian numbers, the mobile number must be 12-digit long. No special
character like "-", "(",")" or anything similar is allowed in the phone number, e.g., 91-98123XXXXX is disallowed.

2.3 Choice between IP address & mobile number authentication

To be able to use our APIs the enterprise needs to choose between 2 access mechanisms -

2.3.1 White listing client public IP addresses –

The series :- 10.0.0.0 through 10.255.255.255
172.16.0.0 through 172.31.255.255 192.168.0.0 through
192.168.255.255 are internal/private IP series and cannot be given for white listing.

2.3.2 Mobile number & password authentication.

● You need supply a Valid mobile number which will be registered for the API account.

6
 BulkSMS API Documentation

● The account details with the password will be shared with you by customer support team.
2.4 SMS Header and Footer
● Messages may need to be sent out with a fixed header and/ or footer in some cases. For instance, an Enterprise would
want all messages to be signed-off with their name or all offers with Terms of Service/ Use. SMS Header and footer
settings can be used for help in this regard.

● If the header is set, all messages sent will be prefixed with the header content. Similarly, if the footer is set, all messages
sent out via the API will end with the footer content.

● For e.g : We have set the header of the message as ‗Dear Customer,‘ and the footer of the message as ‗Happy
Shopping!‘. If the message text: ‗We have come up with a special offer for all our customer with a flat discount of 50%
and more T&C apply. Visit your nearest store.‘ is specified in the API call, the message to the end recipient will be sent
out as: ‗Dear Customer, We have come up with a special offer for all our customer with a flat discount of 50% and more
T&C apply. Visit your nearest store. Happy Shopping!‘. The Header and Footer can be set from the BizBond dashboard
from Keyword -> Message Customization

2.5 API in Asynchronous mode

● Messages can be sent out using Synchronous or Asynchronous mode. In Asynchronous mode, the API call will return
immediately with the Request ID of the call – the complete input validation and message sending will be done
asynchronously –
● This way the call made does not have to wait for the complete processing to be done. In the default mode / synchronous,
on the API will return a very detailed response XML; with the transaction ID, message ID for every message sent.
● To use the API in the asynchronous mode, use the parameter: async =1.
● Here‘s the sample XML returned in Asynchronous API mode:

<RESULT REQID ='29749608774'>

</RESULT>

7
 BulkSMS API Documentation

2.6 Message Types

● The most common message type that needs to be sent out by an Enterprise is a simple text message.
The SMS API can be used to send WAP messages, flash message, Vcard message, as well as UDH. UDH
and Binary messages can be sent using the Single Message API, Here‘s a quick reference guide on the
advanced parameters that needs to be used in each of these cases.

● Table 2-1: The different Message Types

Message Type UDH URL

Message `Name (mtype) (udh) (url) Text
Text (Default) 1 No No Yes

WAP 5 No Yes Yes (optional)

MULTILINGUAL 2 No No Yes

PICTURE 8 No No Yes (Hex Code)

VCARD 11 No No yes

Flash No No Yes
12 (English); 15
(Multilingual)
UDH 13 or 14 ( see UDH Yes No Yes (optional)
message type below )

8
 BulkSMS API Documentation

2.7 How to send UDH (port based) Message

● With a brief example, outlining the sample steps to send UDH messages to a port number using Single
Message API. In addition to the mandatory parameters as outlined in Section 2.9, specify the following:

● Table 2-2: UDH Message Type – additional parameters

Parameter Description

mtype For English text mtype=13 and multilingual mtype=14

udh
User-defined data header. The data header is used for long messages as well as sending
binary content. If you need to send message to specific port (for j2me application to receive),
you may specify the information in udh parameters.
When setting udh, mtype should be 13 or 14.

text Text that needs to be sent on mobile handset. In case of binary content, see 'how to encode
binary message'.

● Step 1 :
Prepare the UDH byte value with message size less than 140 byte, where application running on 5000
port.(hex value
of 5000 = 1388)
06 05 04 13 88 00 00

9
 BulkSMS API Documentation

● Step 2 : Make it 2-character percent-separated hex

%06%05%04%13%88%00%00

Step 3 : URL encode (UTF-8)

%2506%2505%2504%2513%2588%2500%2500

Step 4 : Use URL parameters &udh =%2506%2505%2504%2513%2588%2500%2500

2.7.1 UDH Octet parameter details

Octet Number
Value Description

1 06 Length of the User Data Header

Information Element Identifier (IEI; application port

2 05
addressing scheme,16-bit port address

3 04 Information Element Data Length (IEDL)

Information Element Data (octets 4 & 5 -> 13 88

4-5 13 88
- destination port)

Information Element Data (octets 6 &

6-7 00 00
7 -> 0000 - originator port)

10
 BulkSMS API Documentation

2.7.2 Send Message to a port number with more than 140 bytes,
need to add concatenated message header information

Octet Number Value Description

1 0B Length of the User Data Header

2 5 Information Element Identifier (IEI; application port addressing scheme, 16-bit

port address

3 4 Information Element Data Length (IEDL)

4-5 13 88 Information Element Data (octets 4 & 5 -> 13 88 - destination port)

6-7 00 00 Information Element Data (octets 6 & 7 -> 0000 - originator port)

8 0 Information Element Identifier (IEI; concatenated short message, 8-bit reference

number)

9 3 Information Element Data Length (IEDL)

10 2
Information Element Data (concatenated short message reference number)

11 2 Information Element Data (total number of concatenated messages (0-255)

11
 BulkSMS API Documentation

12 1 Information Element Data (sequence number of current short message)

2.7.3 How to encode Binary message

Step 1. 2-character percent-separated hex

Step 2. url-encode above

Step 3. &text=<output of step 2>

For more details about different octet in UDH header, Plz refer netcore's API document Table 2.2 & 2.3 section.
Note: To send normal text App running on destination port should be able to read ASCII characters. If app understands
binary then message must be in binary encoded rather normal text.

2.8 API Parameters

Parameter Description
This is the unique identifier representing the channel owned by the enterprise/ the
feedid Account ID

To Mobile number (12-digit) or comma separated mobile numbers

Message to be sent to the users. The space within the text message will be replace with
Text ‘+’ sign.

Username It is the 10-digit Mobile Number. This is optional parameter as explained in Section 2.2.
It is the password will be received by SMS after getting registered on our platform. This
Password is an optional parameter, mandatory only when the username is provided.

12
 BulkSMS API Documentation

Make sure that the time is specified in the correct format – yyyymmddhhmm. If time is
not specified message will go immediately. If time is specified in wrong format it won’t
go out. If time parameter is empty or past time is mentioned then message will go
Time immediately.
Using Sender-id is Optional. If there are single or multiple
sender-ids then all the sender-ids have to be validated. For one message only one sender
ID can be used. In case no Sender ID is mentioned in the API call then the default sender
ID is attached to the message. Please speak with your account manager to set the
senderid default sender ID for your account .
Using mtype to indicate the type of message being sent is optional. The default setting is
to send text message. Use mtype as outlined in Section 2.8 (1 – text; 5 – WAP; 8 –
mtype Picture message; 13 – UDH)
URL parameter needs to be specified for WAP Push type messages only. Send the WAP
url URL in this parameter
The data header for UDH Type messages can be specified in this parameter, if message
udh type UDH is chosen.
This is an optional parameter The name of the campaign can be provided in this
jobname parameter. It is used for future reference

entityid This is your enterprise Id registered with TRAI

templateid This is the Id registered with TRAI for template which you are using in SMS
If SMS contains URL which needs to be shortened short=1 needs to be passed (Settings
short should be available to your account for shortening long URL)

13
 BulkSMS API Documentation

2.9 API Responses

Error Code DESC-String Scope Example Description

101 XML MALFORMED REQUEST XML XML does not match with required DTD
MALFORMED.
The end-tag for
element type
"TEXT" must
end with a
'>' delimiter.
102 Client < Account ID> is not REQUEST Client 18888 is If the Account id
registered not registered for the Client is not registered with MyToday
103 Login failed REQUEST Invalid login information entered

104 Credit is insufficient Credit is If the credit for Account expired

REQUEST insufficient
105 <IP address> is not white listed REQUEST 127.40.0.12 IP If the IP of calling client is not registered for Account
is not white-
listed
106 Message Empty MESSAGE When the Message text is blank

107 Message Id not unique REQUEST Mid is not Unique in submitted XML

14
 BulkSMS API Documentation

108 Mobile number SMS Mobile number If invalid mobile number specified
<Mobile Number > invalid 91-9322464675
invalid

109 Sender id <sender id> not SMS Sender ID needs to be registered

registered for account <Account
id>
110 Indexes not unique MESSAGE If a message having two recipient
having same index number
111 <Mobile> User not subscribed to this SMS 99900840096 User
account not subscribed to
this account
112 Message id <id Number > is not an MESSAGE Message id Hello is
Integer not an Integer

113 Index <index Number> is not an integer MESSAGE Index Two is not an Index number of recipient is non numeric
integer

114 <Sender Id> sender id is invalid MESSAGE 12@3 sender id is If sender id Contains special character except Dot(.) and Alpha
invalid numeric greater than 11 char and Numeric > 16 digit

115 Please check that the tag is not greater MESSAGE

than 25 characters or contains special
characters
116 Incorrect Version number MESSAGE Incorrect Version Other than 1.0
number

117 No registered sender MESSAGE

id

118 Long message feature not enabled MESSAGE If message text is greater than 160 characters and for
multi lingual more than 70

119 Multi lingual feature not enabled MESSAGE If message text contains other than English and client has been
not
enabled multi lingual feature

15
 BulkSMS API Documentation

120 MESSAGE 9900000096 If mobile is greater or lesser than 12 digit number and
International SMS feature not enabled International feature has been not enabled

121 Account id <Account Id>invalid MESSAGE Account id India If Account id is non numeric
invalid

122 User name is empty. REQUEST If user does not supply in case user name required

123 Password is empty. REQUEST If user does not supply in case password required

124 User name <User name>not configured, REQUEST User name

Please check with Account Manager. 9900840000 has
not been
configured. Please
check with Account
Manager.
125 Invalid User Name and password REQUEST user name: If specified user name and password mismatch
{9886307244} and
password do not
match
126 REQUEST Access denied User
9900840000 does not
Access denied User have rights to use the
<User name> does not have rights to API. Please check
use the API. Please check with Account with Account
Manager. Manager.
127 REQUEST Conflict, more than Role configuration incorrect. If you get this Error - Contact your
one Account Manager.
Conflict, more than one BULKPUSHAPI BULKPUSHAPI
role exists for user role exists for user
<User name> 9900840000.

16
 BulkSMS API Documentation

128 REQUEST Access denied to

URL
http://XXX/BulkSms
/UploadCsvFile for
user name
9900840000.
Access denied to URL <URL> for user Please
name <User name>. Please check with check with Account
Account Manager. Manager.
129 Invalid Time REQUEST Correct Time is not
been specified
20080930130
130 Invalid Expiry Time REQUEST If expiry time is not Expiry time configuration incorrect. . If you get this Error - Contact
numeric in database your Account Manager.
Example: a124
131* NDNC Status is currently unavailable REQUEST Message to user This happens when the system is unable to get the NDNC status for a
91990084xxxx particular mobile number.
rejected, since the
NDNC Status is
currently unavailable.
This means that
MyToday has not yet
checked with the
NDNC registry about
the status.
132* The user is registered for NDNC REQUEST Message to user This happens when the user is registered with NDNC & doesn't wish to
91990084xxxx receive sms.
rejected, since the
user is registered for
NDNC and it means
that user does not
want to receive any
unsolicited
messages

17
 BulkSMS API Documentation

136* The user NDNC REQUEST Message to user This happens when
status unknown 91990084xxxx the
rejected, since the NDNC status is not available for that particular user
user NDNC status
unknown. This is the
case when NDNC
registry does not
know the status of the
mobile number. This
happens when a
number is in the
market while NDNC
is not available of
its existence.
-1 Invalid Request Format REQUEST Feed id is empty , If record does not full fill required standard
Mobile number is
empty

*The error codes 131, 132, 136 occur only if the channel is set-up for NDNC validation.

Please find below few more error codes that can occur

Error Code Description

137 There is an error in the account setting. Please contact your Account Manager

138 Error occurred while contacting payment portal ,Please try after some time or write us to [email protected]

139 Sorry Account not exist ,Please contact account manager or write us to [email protected]

140 Invalid message transaction id,Please give greater than %s -- Deprecated

18
 BulkSMS API Documentation

141 Message type [%s] invalid or Not supported

142 URL parameter [%s] is empty for message type [%s ]

143 Ambiguity,For Message type [%s] Can not have [%s] data

144 Message type [%s] Not supported to DIY user [%s]

145 Found duplicate Request with msgid %s,Request dropped

146 Message to user %s rejected,Since message can not be schedule after 30 days

147 User %s scheduled for NDNC hibernate has been expired -- Deprecated

148 %s is blacklisted senderid

149 %s is not whitelist virtual senderid

150 Promotional Message to user %s rejected ,Since publish or schedule hour %s falls between TRAI Do not call

151 Request_id- %s,Txid- %s, Senderid- %s, Message to user- %s dropped due to insufficient balance

152 Duplicate mobile number [%s] for a message

2.10 Single Message API

2.10.1 Using GET method

This API allows an enterprise to send a single message to one or more mobile numbers (Maximum of 50 Mobile

19
 BulkSMS API Documentation

numbers) at one time. This is achieved by issuing a HTTP GET request to our server listening at
https://bulkpush.mytoday.com/BulkSms/SingleMsgApi with following GET parameters that must be URL
encoded.

Sample request :

https://test1bulksms.mytoday.com/BulkSms/SingleMsgApi?feedid=<account_id>&username=<username>&password=<password>&
To=<mobile>&Text=<message>&templateid=<templateid>&entityid=<entityid>&async=<1/0>&short=<1/0>

Sample success Sync Response :

Sample success Aync response : <RESULT REQID ='29749608775'>
<RESULT REQID ='29749608774'> <MID SUBMITDATE='2020-09-16 21:54:47' ID='1' TAG = 'null' TID =
</RESULT> '80471331642'>
</MID>
</RESULT>

2.10.2 Using POST method

This API usage is different than the previous one as it allows you to upload up-to 10,000 messages.

POST /BulkSms/SingleMsgApi? HTTP/1.1

20
 BulkSMS API Documentation

Host: test1bulksms.mytoday.com
Content-Type: application/x-www-form-urlencoded

feedid=<feedid>&username=<username>&password=<password>&To=<mobile/commaseparatedmobiles>&Text=<SMSText>&templa
teid=<templateid>&entityid=<entityid>&async=<1/0>

Sample Curl Request :

curl --location --request POST 'https://test1bulksms.mytoday.com/BulkSms/SingleMsgApi' \

--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'feedid=accountid' \
--data-urlencode 'username=username' \
--data-urlencode 'password=password' \
--data-urlencode 'To=mobile' \
--data-urlencode 'Text=Message' \
--data-urlencode 'templateid=templateid' \
--data-urlencode 'entityid=entityid'\
--data-urlencode 'short=1/0'\
--data-urlencode 'async=1/0'

2.11 CSV Message API

21
 BulkSMS API Documentation

The API allows an enterprise to upload multiple messages at a time by creating a file containing mobile numbers and the
corresponding messages (either same message to everyone or different messages).

2.11.1 [POST] CSV uploads using ‘filestring’ parameter

Sample Curl Request :

curl --location --request POST 'https://test1bulksms.mytoday.com/BulkSms/UploadCsvFile' \

--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'feedid=<account_id>' \
--data-urlencode 'username=<username>' \
--data-urlencode 'password=<Password>' \
--data-urlencode 'filestring=<Mobile>,"SMS","senderId","Futuretime","MessageId","Templateid"' \
--data-urlencode 'templateid=<templateid>' \
--data-urlencode 'entityid=<entityid>'\
--data-urlencode 'async=<0/1>'\
--data-urlencode 'short=<0/1>'

2.11.2 [GET] CSV uploads using ‘filestring’ parameter

Sample Curl Request :
curl --location --request GET
'https://test1bulksms.mytoday.com/BulkSms/UploadCsvFile?feedid=<accountid>&filestring=mobile%2C%22<URLENcodedSMS>%2
2%2C%22<SenderId>%2C%22<Future time>%22%2C%22<templateid>%22&async=0/1&short=0/1'

22
 BulkSMS API Documentation

2.11.3 [Post] CSV uploads in the file format

Sample Curl Request :

curl --location --request POST 'https://test1bulksms.mytoday.com/BulkSms/UploadFormFile' \

--form 'upload=<filenamewithlocation>' \
--form 'feedid=<Account_id>' \
--form 'entityid=<entityid>' \
--form 'username=<username>' \
--form 'password=<password>' \
--form 'Async=<1/0>' \
--form 'short=<1/0>'

Sample CSV File format

Accepted formats : zipped csv , .csv

CSV columns : "Mobile","SMS","Sender Id","Optional Future Time ","Optional message Tag","Template Id"

2.12 XML Message API

This API allows an enterprise to send multiple messages to users via XML. Same message can be specified for all users, or
different
messages could be specified to different users.

Different Sender ID can be specified for different messages – the Sender IDs need to be white-listed with Netcore prior to
use – else the
default Sender ID set for the enterprise account will be used to send messages to users.

23
 BulkSMS API Documentation

UserRequest: The XML file containing the account and message details. The XML File must be submitted as The XML file
must be
URL- encoded and XML-encoded.

Base API is:

Production :

https://bulkpush.mytoday.com/BulkSms/SendSms

Stage :
https://test1bulksms.mytoday.com/BulkSms/SendSms

Sample XML

<!DOCTYPE MESSAGE SYSTEM 'https://bulkpush.mytoday.com/BulkSms/BulkSmsV1.00.dtd'>

<MESSAGE>
<VER>1.0</VER>
<REQID>Reqid</REQID>
<USER>
<USERNAME>Username</USERNAME>
<PASSWORD>Password</PASSWORD>
</USER>
<SMS>
<ENTITYID>Entityid</ENTITYID>
<TEMPLATEID>Templateid</TEMPLATEID>
<TEXT>Text</TEXT>

24
 BulkSMS API Documentation

<ID>123</ID>
<ADDRESS FROM="Senderid" TO="mobile1" SEQ="1"/>
<ADDRESS FROM="Senderid" TO="mobile2" SEQ="2"/></SMS>
</MESSAGE>

2.12.1 Special characters conversion

While creating the messages – all special characters need to be escaped. Do find the table below that describes the
conversion of these special characters.

Code Character Replace with

Tab(\t) &#009;
Single Quote( ' ) &apos;

Double Quote ( ― ) &quot;

New Line(\n) &#010;

Ampersand(&) &amp;

Percentage (%) &#37;

Greater than(>) Lesser than(<) &gt; &lt;

\f &#012;

You may use the same conversion if you choose to insert special characters in the tag parameter – but we don’t recommend it.
2.12.2 DTD for input XML

The DTD of the XML with mobile-message-sender ID input is as follows:

25
 BulkSMS API Documentation

<!ELEMENT REQ (VER,USER?,ACCOUNT,MODE?,NET-MODE?,MESSAGE+)>

<!ELEMENT MODE (#PCDATA)>
<!ELEMENT NET-MODE (#PCDATA)>
<!ELEMENT VER (#PCDATA)>
<!ELEMENT USER (USERNAME?,PASSWORD?)>
<!ELEMENT USERNAME (#PCDATA)>
<!ELEMENT PASSWORD (#PCDATA)>
<!ELEMENT ACCOUNT (ID)>
<!ELEMENT ID (#PCDATA)>
<!ELEMENT MESSAGE (TAG?,TEXT?,DLR?,TYPE?,MID,VALIDITY?,HIBERNATE?,URL?,UDH?,SMS+)>
<!ELEMENT TEXT ANY>
<!ELEMENT TAG ANY>
<!ELEMENT MID (#PCDATA)>
<!ELEMENT DLR (#PCDATA)>
<!ELEMENT TYPE (#PCDATA)>
<!ELEMENT VALIDITY (#PCDATA)>
<!ELEMENT HIBERNATE (#PCDATA)>
<!ELEMENT URL (#PCDATA)>
<!ELEMENT UDH (#PCDATA)>
<!ELEMENT SMS EMPTY> <!ATTLIST SMS FROM CDATA #IMPLIED
TIME CDATA #IMPLIED TO CDATA #REQUIRED INDEX
CDATA #REQUIRED TAG CDATA #IMPLIED>

Table 2-6: Explanation of the different input XML Tags

26
 BulkSMS API Documentation

Element Description Mandatory Default value Examples

None, should be 1.0 for this initial

VER Version Yes release 1

USERNAME User name of client-ten digit mobile number No None 996766666

PASSWORD Password corresponding to the above user name No None ourtomorrow

Message Type
0 – Plain Text SMS 1 – Flash SMS
TYPE And so on. Currently only plain text sms is supported No 0 0

ACCOUNT The account details of the user Yes None

This specifies the level at which we perform subscriber

checking
Default no checks performed for the receiver of the sms

.
MODE is the receiver subscribed to the account id or not. No 0 0

27
 BulkSMS API Documentation

The account id. It is against this id that we validate the

Sender ids, credits and other attributes. Ids
ACCID should be valid integers Yes None 1410

Encapsulates a content block. Multiple MESASGE blocks

MESSAGE are allowed. Yes None

A text that identifies the message. This text is supplied by

the client. The response will contain this tag along with the
message id. Minimum 7 chars and max 25 chars if present.
Allowed chars [A-
TAG Z a,z 0-9, _, <space>] No None Winner message

28
 BulkSMS API Documentation

Unique ID of message supplied by the client. The client

sends this value. This has to be unique per MID in a
request. The server sends this v a l u e b a c k t o the client
in response to the client request. Each MESSAGE tag must
contain an unique value for ID within the
ID request Yes None 1234

The message we have to send to the mobile number(s).

Please see the Section 2.3 for the list of Congratulations on winning t h
TEXT characters to be escaped Yes None e AUDI TT.

This flag i n d i c a t e s whether t h e service shall ask for

delivery reports or no. 0 is NO DLR required 1 is Yes DLR
DLR is required. No 0 1

29
 BulkSMS API Documentation

This flag is used to indicate the Message type that needs to

be sent: (1 – text; 5 – WAP; 7 – Mono ringtone; 10 – Non-
Nokia mono ringtone; 8 – Picture message; 13 – UDH). For 5
TYPE details, refer to Section 2.8 No 1 (to send WAP messages)

Set this validity of a message to current SMSC time plus

minutes specified in validity field. SMSC will not try to send
the message after the validity have expired. 0 is infinite
VALIDITY validity No 0 10

If your Account is NDNC-Check enabled, messages will be

sent out only to users who are not registered with NDNC.
The platform will also reject numbers for whom the status is 1 to retry send ing messages
unavailable at the point of message send – to retry these that were rejected d u e to
messages when mobile NDNC statu s unavailability or
HIBERNATE NDNC Status is available, set this attribute to 1 No 0 expiry at the po int of sms send

30
 BulkSMS API Documentation

Specify the URL that needs to be sent out in the WAP Push
URL message using this No - http://mytoday.com

Use this parameter to specify the user-defined header while %2506%2505%25

sending message to an application 04%2515%2582%
UDH port number No - 2500%2500

This tag contains the details of the person receiving the No values. All values are
SMS sms the attributes are explained below Yes None supplied in the attributes

FROM The sender of the message No Default sender registered with us MyToday

Person receiving the SMS. See section 2.2 to know more

TO about Mobile number guidelines Yes None 919967025255

Unique Sequence ID. Must be an integer and must be

unique to each recipient. While checking message status
you must send this
INDEX value. Yes None Any integer like 1, 154, 3004

31
 BulkSMS API Documentation

A text that identifies the recepient. This text is supplied by

the client. Minimum 7 chars and max 25 chars if present.
TAG Allowed chars [A- Z a,z 0-9, _, <space>] No None Winner message

Time at which the message needs to be sent. Messages

can‘t be scheduled for future yet. If time specified is less
than current time, current time is assumed. Time Format
TIME should be yyyymmddhhmm No Current Time 200802011700

32
 BulkSMS API Documentation

2.12.3 DTD for output XML

The XML API call returns an XML Response which acknowledges the
receipt of the request.

<!ELEMENT CODE ( #PCDATA ) >

<!ELEMENT DESC ( #PCDATA ) >
<!ELEMENT ERROR ( CODE?, DESC?, ERROR* ) >
<!ELEMENT REQUEST-ERROR ( ERROR ) >
<!ATTLIST ERROR INDEX NMTOKEN #IMPLIED )>
<!ELEMENT MID ( ERROR* ) >
<!ATTLIST MID ID NMTOKEN #REQUIRED >
<!ATTLIST MID SUBMITDATE CDATA #REQUIRED >
<!ATTLIST MID TAG NMTOKEN #IMPLIED >
<!ATTLIST MID TID NMTOKEN #IMPLIED >
<!ELEMENT RESULT ( REQUEST-ERROR|MID+ ) >
<!ATTLIST RESULT REQID NMTOKEN #IMPLIED >

The format of the response is as follows - RESULT tag will always be present.
The tag REQUEST-ERROR will follow if it‘s a global error like invalid request.
Explanation of the different output XML Tags

Element Description

CODE Numeric value – when an error occurs – this contains the numeric code for the error

DESC This is the text description of the error

MID Message ID as mentioned in the input XML,

ID ID for the record as mentioned in the input XML

33
 BulkSMS API Documentation

In case of successful handling this is the transaction ID as returned by our platform. The same can be
TID used to later fetch the delivery reports for the records processed.

2.13.4 Using GET method

We show here a sample piece of code where this API is
being used through the GET method of HTTP call. Note that
the parameter UserRequest takes the XML input which XML
file that was URL encoded above for GET call of the API.

BaseURL:
https://test1bulksms.mytoday.com/BulkSms/SendSms

Sample Format:

<!DOCTYPE REQ SYSTEM 'https://bulkpush.mytoday.com//BulkSms/BulkSmsV1.00.dtd'><REQ><VER>1.0</VER>

<USER><USERNAME>User</USERNAME><PASSWORD>password</PASSWORD></USER><ACCOUNT><ID>feedid</ID><ENTITY
ID>ENTITYID</ENTITYID></ACCOUNT><MESSAGE><TEMPLATEID>TEMPLATEID</TEMPLATEID><TEXT>Message</TEXT><T
YPE>0</TYPE><MID>1</MID><SMS FROM='Senderid' TO='Mobile' INDEX ='1'></SMS></MESSAGE></REQ>

Sample request :

https://test1bulksms.mytoday.com/BulkSms/SendSms?UserRequest=%3C!DOCTYPE%20REQ%20SYSTEM%20%27https%3A%2F%2Ffanyv88.com%3A443%2Fhttp%2Fbulkpush.myt
oday.com%2F%2FBulkSms%2FBulkSmsV1.00.dtd%27%3E%3CREQ%3E%3CVER%3E1.0%3C%2FVER%3E%0A%3CUSER%3E%3CUSERNAME%3EUser%3C%2FUS
ERNAME%3E%3CPASSWORD%3Epassword%3C%2FPASSWORD%3E%3C%2FUSER%3E%3CACCOUNT%3E%3CID%3Efeedid%3C%2FID%3E%3CENTITYID%3EENTIT
YID%3C%2FENTITYID%3E%3C%2FACCOUNT%3E%3CMESSAGE%3E%3CTEMPLATEID%3ETEMPLATEID%3C%2FTEMPLATEID%3E%3CTEXT%3EMessage%3C%2FT
EXT%3E%3CTYPE%3E0%3C%2FTYPE%3E%3CMID%3E1%3C%2FMID%3E%3CSMS%20FROM%3D%27Senderid%27%20TO%3D%27Mobile%27%20INDEX%20%3D%2
71%27%3E%3C%2FSMS%3E%3C%2FMESSAGE%3E%3C%2FREQ%3E%0A

34
 BulkSMS API Documentation

Output for the given above given sample of API call using GET method -

Sample success output:

<!DOCTYPE RESULT SYSTEM

'https://bulkpush.mytoday.com/BulkSms/BulkSmsRespV1.00.dtd'>
<RESULT REQID ='3738'>
<MID SUBMITDATE='2008-09-26 16:47:38' ID='1' TAG = 'null' TID = '574795'>
</MID>
<MID SUBMITDATE='2008-09-26 16:47:38' ID='2' TAG = 'null' TID = '574796'>

</MID>
</RESULT>

2.14 JSON Message API

This API allows an enterprise to send multiple messages to users via JSON.
Same message can be specified for all users, or different
messages could be specified to different users.
The API is available in both Get & Post Methods.

Different Sender ID can be specified for different messages – the Sender

IDs need to be white-listed with Netcore prior to use – else the
default Sender ID set for the enterprise account will be used to send
messages to users.

35
 BulkSMS API Documentation

Json : The json parameter containing the account and message details.

2.14.1 JSON Single Message API

Base URL

Staging :
https://test1bulksms.mytoday.com/BulkSms/JsonSingleApi

Production :
https://bulkpush.mytoday.com/BulkSms/JsonSingleApi

Sample Payload

{"feedid":feedid,"username":Username,"password":"password","jobname":"Jobname/Messagetag","mobile":Mobile,"messages":"SM
S","templateid":"TemplateId","entityid":"EntityID"}

Sample Success Response :

{"req_id":"29749608791",
"status":"success",
"submittedAt":"2020-09-17 00:49:54"}

36
 BulkSMS API Documentation

2.14.2 Bulk JSON API

Base URL

Staging :
https://test1bulksms.mytoday.com/BulkSms/JsonBulkApi

Production :
https://bulkpush.mytoday.com/BulkSms/JsonBulkApi

Sample Payload

{"feedid":"Feedid","username":"","password":"","jobname":"","entityid":"entityid",
"Data":[{"mobile":"Mobile1","messages":"message","senderid":"","msgId":"", "templateid":"templateid"},
{"mobile":"Mobile2","messages":"message","senderid":"","msgId":"", "templateid":"templateid"}]}

Sample Success Response :

{
"req_id":"29749608793",
"status":"success",
"submittedAt":"2020-09-17 01:04:27"
}

37
 BulkSMS API Documentation

2.15 Error Responses

In case the Enterprise Account/ Channel has not been registered with us:

<!DOCTYPE RESULT SYSTEM

'https://bulkpush.mytoday.com/BulkSms/BulkSmsRespV1.00.dtd'>
<RESULT>
<REQUEST-ERROR>
<ERROR>
<CODE>102</CODE>
<DESC>Client 18244 is not registered</DESC>
</ERROR>
</REQUEST-ERROR>
</RESULT>

In case the credits have expired/ are insufficient in the Enterprise

Account:

<!DOCTYPE RESULT SYSTEM

'https://bulkpush.mytoday.com/BulkSms/BulkSmsRespV1.00.dtd'>
<RESULT>
<REQUEST-ERROR>
<ERROR>
<CODE>104<CODE>
<DESC> Credit not sufficient </DESC> </ERROR>
</REQUEST-ERROR>
</RESULT>

38
 BulkSMS API Documentation

Multi Lingual not enabled & the message is multi-lingual

<!DOCTYPE RESULT SYSTEM

'https://bulkpush.mytoday.com/BulkSms/BulkSmsRespV1.00.dtd'>
<RESULT>
<ERROR >
<CODE>119<CODE>
<DESC> Multi lingual feature not enabled</DESC>
</ERROR>
</RESULT>

International not enabled on feed but mobile number mentioned in request is

international

<!DOCTYPE RESULT SYSTEM

'https://bulkpush.mytoday.com/BulkSms/BulkSmsRespV1.00.dtd'>
<RESULT>
<ERROR >
<CODE>120<CODE>
<DESC>International feature not enabled</DESC>
</ERROR>
</RESULT>

This Response XML means that there was error in the formation of the complete
input XML.
<!DOCTYPE RESULT SYSTEM
'https://bulkpush.mytoday.com/BulkSms/BulkSmsRespV1.00.dtd'>
<RESULT>

39
 BulkSMS API Documentation

<REQUEST-ERROR><ERROR>
<CODE>-1</CODE><DESC>Invalid record format</DESC></ERROR></REQUEST-ERROR> </RESULT>
Insufficient Credits
<!DOCTYPE RESULT SYSTEM
'https://bulkpush.mytoday.com/BulkSms/BulkSmsRespV1.00.dtd'>
<RESULT>
<REQUEST-ERROR>
<ERROR>
<CODE>104<CODE>
<DESC> Credit not sufficient </DESC>
</ERROR>
</REQUEST-ERROR>
</RESULT>

The error that is returned, if the XML format/ input format is incorrect
<!DOCTYPE RESULT SYSTEM
'https://bulkpush.mytoday.com/BulkSms/BulkSmsRespV1.00.dtd'>
<RESULT>
<REQUEST-ERROR>
<ERROR>
<CODE>101</CODE>
<DESC>XML MALFORMEDnull</DESC>
</ERROR>
</REQUEST-ERROR>
</RESULT>

Account used in request is not registered .

<!DOCTYPE RESULT SYSTEM'https://bulkpush.mytoday.com/BulkSms/BulkSmsRespV1.00.dtd'> <RESULT>

40
 BulkSMS API Documentation

<REQUEST-ERROR><ERROR><CODE>102</CODE><DESC>Client 18244 is not registered</DESC></ERROR></REQUEST-

ERROR></RESULT>

Message valid, Mobile numbers invalid

In the following example, the text is intended to be sent to 3 recipients, out of which
2 recipients have invalid mobile numbers.

When this happens, the API will send out 1 message for which the
number has been specified correctly, and return an error for the
other 2 mobile numbers.

<!DOCTYPE REQ SYSTEM

'https://bulkpush.mytoday.com/BulkSms/BulkSmsV1.00.dtd'>
<REQ>
<VER>1.0</VER>
<ACCOUNT>
<ID>38244</ID>
</ACCOUNT>
<MESSAGE>
<TAG>hello</TAG>
<TEXT>text on two lines </TEXT>

< TYPE>0</TYP E>

<MID>1</MID>
<SMS FROM='' TO = '919886080768' INDEX = '1' TAG = ''></SMS>
<SMS FROM='MyToday' TO = '+919886080769' INDEX = '2' TAG = ''></SMS>
<SMS FROM='MyToday' TO = '+919886080769' INDEX = '3' TAG = ''></SMS>
</MESSAGE>
< /REQ >

41
 BulkSMS API Documentation

<!DOCTYPE RESULT SYSTEM

'https://bulkpush.mytoday.com/BulkSms/BulkSmsRespV1.00.dtd'>
<RESULT REQID ='835'>
<MID SUBMITDATE='2008-05-27 17:09:19' ID='1' TAG = 'hello' TID = '121136'>
<ERROR INDEX = '2'>
<ERROR>
<CODE>108</CODE>
<DESC>Mobile number +919886080769 invalid</DESC>
</ERROR>
</ERROR>
<ERROR INDEX = '3'>
<ERROR> <CODE>108</CODE>
<DESC>Mobile number +919886080769 invalid</DESC>
</ERROR>
</ERROR> </MID>
</RESULT>

2.16 Using HTTPS for APIs

■ To invoke our APIs using HTTPS, one needs to replace "http://" with
"https://" in the URI, or Web address.

■ When a user connects to a website via HTTPS, the website encrypts

the session with a digital certificate.

■ You can send secured requests to the bulkpush.mytoday.com using

HTTPS Connection.

42
 BulkSMS API Documentation

■ The bulkpush.mytoday.com server listens on port 443 and expects an

encrypted request. To make secured HTTPS requests to the bulk-
push API, instantiate an open SSL enabled net http client.

■ Now you can call any of the APIs using

https://bulkpush.mytoday.com/BulkSms/

■ If not already installed, you might have to install the open SSL
extension to use HTTPS URLs. If you keep trusted certificates on your
computer, you can have Open-SSL verify the server's certificates. If
not, your conversation with the server will be confidential, but you won't
be able to definitively authenticate the server. It might be an impostor.

● On Debian/Linux the CA-Certificates package installs a set of trusted

server certificates in the directory /etc/ssl/certs. You can set the
object's certificates- authority path to that directory and set the verify
mode to verify-peer.

● Now Open-SSL can verify that you are actually talking to the web server
at bulkpush.mytoday.com and not an impostor.

● The SSL certificate for mytoday.com is signed by Digicert.If you already

have Digicert certificate installed on your computer, you can verif y
bulkpush.mytoday.com's signature. That is "If I trust Digicert, I can trust
mytoday.com".

43
 BulkSMS API Documentation

Chapter 3
3.1 Methods to Fetch Delivery reports
3.1.1 Reports VIA Bizbond Panel:
You can download the delivery reports from BizBond Panel for the same you
need to login to http://biz.mytoday.com/web/ link, then click on Reports tab.
You will get to below page

44
 BulkSMS API Documentation

To download details reports use first option “Download Detailed

Reports for “ , use select and click on download. Second option
”Search From” can be used for searching delivery status of one mobile
number for single day from single channel.

3.1.2 Delivery Reports VIA API

The base URL for Delivery Reports will be:
http://stats.mytoday.com/dlr_api

Steps for calling API

45
 BulkSMS API Documentation

1. You need to call the API:

http://stats.mytoday.com/dlr_api?feedid=12345&date=2009-12-05

Feedid is a mandatory parameter for which you must specify a value.

Date is one of the optional parameters. If do not specify a
date, by default, the delivery report for today’s date will be shown.
Refer to API Parameters for API Parameters.

If there is any error while specifying the API parameters, error

message will be displayed corresponding to the type of error.

When you call the API, the Delivery Report Request Transaction ID
will be returned. This will need to be used for further
requests to fetch the Delivery Report.

<RESULT>DTXNID</RESULT> DTXNID is the Delivery Report Request Transaction ID. It is alphanumeric.

2. For consequent requests to fetch the Delivery Report, the API needs to
be invoked the DLR Request Transaction ID parameter (dtxnid=<DTXNID>):

http://stats.mytoday.com/dlr_api?feedid=12345&date=2009-12-05&dtxnid=6xyjiulsd24afsf

You get the status as-

<RESULT>FETCHING<RESULT>
Or
<RESULT>DONE</RESULT>

46
 BulkSMS API Documentation

FETCHING implies that the Delivery Report retrieval is in progress. The

API needs to be invoked in a loop till status is returned as
DONE. DONE status indicates that the delivery report can be retrieved in
the next API call.

3. Resend the API request, with an additional parameter ack=1:

http://stats.mytoday.com/dlr_api?feedid=12345&date=2009-12- 05&dtxnid=6xyjiulsd24afsf&ack=1

The Delivery Report will be available in the required format.

3.1.3 Delivery Reports VIA Ping Back

Using this option we can pingback delivery reports to customers in real time.
For the same customers need to provide the pingback URL and delivery reports parameters

47
 BulkSMS API Documentation

which needs to be pass.

Below is the example of delivery reports Ping Back:

This will be a http GET call to the URL provided by

you.

For better scaling and support, these are the few parameters:

Parameters Field type Sample Data Description

the id that is originally returned to the client per request.

reqid character 3453456723

integer (upto 64
mobile 919000000000 the mobile number tat message was sent to
bytes)

2009-02-20
delv_date datetime the date and time when message was delivered.
00:00:00

Status will be S for submit / N for Not-Delivered /

status char S
D for delivered

feedid integer (upto 64 534867 The feedid from which client sent the message
bytes)

Sample URL will be like:

https://www.xyz.com/dlrnotification.jsp?reqid=3453456723

48
 BulkSMS API Documentation

3.1.4 Delivery reports Via FTP/SFTP upload

This is simple way of delivery reports sharing in which complete days delivery
reports will be uploaded on FTP location shared by client

3.2 Delivery status description:-

● Delivered - Delivered numbers.

● Absent subscriber - These are the users who are continuously
coming in/out Network because of which the message did not
get delivered. Here we retry the message for 4 hours
from the Gateway and if still it fails then we put him
in the same status in reports.
● Invalid subscriber -

■ These are the users for whom we received a

response that this is an Invalid user from the
operator when we tried sending the message to
them. If required we can give you the confirmed
invalid numbers.

■ There can also be a case when you push the

message to 10 digit mobile number, but that
number is not Active use. It may also be a case,
that the number is with the SIM card seller and it
has not been purchased so far.

■ You have sent a message to a number which is

not a valid 10 digit or 12 digit (with '91' as prefix)
mobile number.

49
 BulkSMS API Documentation

● SMS/Message Inbox full - As the name suggests these are the

users whose handset inbox was full when the message was tried to
be delivered to them.

● Blacklist - These are blacklisted numbers at the Operator end.

○ Probable Reasons for blacklisting:

○ The number might have been used for illegal activities in past
○ Nonpayment of bills
○ The number might belong to a V.V.VIP person of an organization

○ The number might belong to an VVIP Government official,

minister, etc.

○ Government of India has asked all operators to not send sms to

that number.

○ Complaints from other mobile users about that number

○ User might have done many complaints to operator/TRAI

regarding unsolicited sms being received by him.

● NDNC Reject - These are the numbers registered in NCPR database.

● Undelivered - These are the users for whom message got

failed after multiple retries due to various reasons like operator
end/user end issues.

● Submitted to Network - These are the messages for which we

haven't received the delivery reports from the Operator. But, it
doesn't mean that the message were not Delivered to the end user.
As per our observation, 85 to 90% of messages are delivered to the

50
 BulkSMS API Documentation

end user, but we haven't received delivery

acknowledgement/reports from the Operator. In such scenario, we
wait for approximately 24 to 48 hours for the reports to arrive from
the Operator end. If the reports are received, those are updated in
the Online panel instantly. In case, if the reports are not received,
the delivery status will remain as 'Submitted to n/w'
● Dropped -

a. These are the numbers belonging to J&K (Jammu and

Kashmir) series. There is ban from Govt of India since past
few years, because of which sms cannot be delivered on
these numbers.

or

b. Dropped by the operator from their end. Services to the

SIM card (mobile number) will be discontinued from the
Operator, if there is no usage i.e no voice calls
(incoming & outgoing) , SMS and data for any
continuous period of 60 days from the date of first call.

● Expired - These are the numbers to which the messages are not delivered
after multiple retires from the Operator end because of the remote operator
end issues.

● International Roaming: These are the users who are in International

roaming with Indian numbers at the time when the message
was pushed to them.

● Force Expired - These are the numbers to which messages are dropped
due to rules in our system or due to invalid numbers in the uploaded base
or the client has requested to drop the messages.

● Duplicate Message Drop : If the same message content is sent on the

same mobile number within 30 min, the duplicate messages will be

51
 BulkSMS API Documentation

dropped.

● Pending - These are the messages which are not sent out of our system.

52