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 4

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

2
 BulkSMS API Documentation

2.11 CSV Message API 20

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

Chapter 3 42

3.1 Methods to Fetch Delivery reports 42

3.1.1 Reports VIA Bizbond Panel: 42
3.1.2 Delivery Reports VIA API 43
3.1.3 Delivery Reports VIA Ping Back 45
3.1.4 Delivery reports Via FTP/SFTP upload 46

3.2 Delivery status description:- 46

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

1.4 Contact Details

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

4
 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.

5
 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>

6
 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 )

7
 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

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

8
 BulkSMS API Documentation

%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)

9
 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)

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

10
 BulkSMS API Documentation

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.

11
 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)

12
 BulkSMS API Documentation

2.9 API Responses

Error DESC-String Scope Example Description
Code
101 XML MALFORMED REQUEST XML MALFORMED. XML does not match with required DTD
The end-tag for
element type "TEXT"
must end with a
'>' delimiter.

102 Client < Account ID> is not registered REQUEST Client 18888 is not If the Account id
registered for the Client is not registered with MyToday
103 Login failed REQUEST Invalid login information entered

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

105 <IP address> is not white listed REQUEST 127.40.0.12 IP is not If the IP of calling client is not registered for Account
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

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

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

13
 BulkSMS API Documentation

id>

110 Indexes not unique MESSAGE If a message having two recipient

having same index number
111 <Mobile> User not subscribed to this account SMS 99900840096 User not
subscribed to this account

112 Message id <id Number > is not an Integer MESSAGE Message id Hello is not an
Integer
113 Index <index Number> is not an integer MESSAGE Index Two is not an integer Index number of recipient is non numeric

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

115 Please check that the tag is not greater than 25 MESSAGE
characters or contains special characters

116 Incorrect Version number MESSAGE Incorrect Version number Other than 1.0

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
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 invalid If Account id is non numeric

14
 BulkSMS API Documentation

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

Please check with Account Manager.
User name 9900840000 has
not been configured. Please
check with Account
Manager.
125 Invalid User Name and password REQUEST If specified user name and password mismatch

user name: {9886307244}

and password do not match
126 REQUEST Access denied User
9900840000 does not have
rights to use the API. Please
Access denied User
check with Account Manager.
<User name> does not have rights to use the
API. Please check with Account Manager.
127 REQUEST Role configuration incorrect. If you get this Error - Contact your
Account Manager.
Conflict, more than one BULKPUSHAPI Conflict, more than one
role exists for user BULKPUSHAPI role exists
<User name> for user 9900840000.
128 REQUEST

Access denied to URL

http://XXX/BulkSms/Upload
CsvFile for user name
Access denied to URL <URL> for user name 9900840000. Please
<User name>. Please check with Account check with Account
Manager. Manager.
129 Invalid Time REQUEST Correct Time is not been
specified 20080930130

15
 BulkSMS API Documentation

130 Invalid Expiry Time REQUEST If expiry time is not numeric in Expiry time configuration incorrect. . If you get this Error - Contact
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 rejected, since particular mobile number.
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 rejected, since receive sms.
the user is registered for
NDNC and it means that user
does not want to receive any
unsolicited
messages

136* The user NDNC REQUEST Message to user This happens when
status unknown 91990084xxxx rejected, since the
the user NDNC status NDNC status is not available for that particular user
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.

16
 BulkSMS API Documentation

-1 Invalid Request Format REQUEST Feed id is empty , Mobile If record does not full fill required standard
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

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

17
 BulkSMS API Documentation

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
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>

18
 BulkSMS API Documentation

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

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 :

19
 BulkSMS API Documentation

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

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>'\

20
 BulkSMS API Documentation

--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<Optional
tag>%22%2C%22<templateid>%22&async=0/1&short=0/1&entityid=<PE ID>'

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

21
 BulkSMS API Documentation

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.

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

22
 BulkSMS API Documentation

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>
<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

23
 BulkSMS API Documentation

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:

<!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)>

24
 BulkSMS API Documentation

<!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

Elem
ent 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

25
 BulkSMS API Documentation

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

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 are

MESSAGE allowed. Yes None

26
 BulkSMS API Documentation

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

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.

27
 BulkSMS API Documentation

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

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

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 details, refer to 5
TYPE 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
VALIDITY after the validity have expired. 0 is infinite validity No 0 10

28
 BulkSMS API Documentation

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

only to users who are not registered with NDNC. The platform will 1 to retry send ing messages
also reject numbers for whom the status is unavailable at the point that were rejected d u e to
of message send – to retry these 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

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 sending %2506%2505%25
message to an application 04%2515%2582%
UDH port number No - 2500%2500

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

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

29
 BulkSMS API Documentation

Person receiving the SMS. See section 2.2 to know more about
TO 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

A text that identifies the recepient. This text is supplied by the client.
Minimum 7 chars and max 25 chars if present. Allowed chars [A- Z
TAG 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,
TIME current time is assumed. Time Format should be yyyymmddhhmm No Current Time 200802011700

30
 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

31
 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

32
 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.

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

33
 BulkSMS API Documentation

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"}

34
 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"
}

35
 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>

36
 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>
<REQUEST-ERROR><ERROR>
<CODE>-1</CODE><DESC>Invalid record format</DESC></ERROR></REQUEST-ERROR> </RESULT>

37
 BulkSMS API Documentation

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>
<REQUEST-ERROR><ERROR><CODE>102</CODE><DESC>Client 18244 is not registered</DESC></ERROR></REQUEST-
ERROR></RESULT>

38
 BulkSMS API Documentation

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 >

<!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'>

39
 BulkSMS API Documentation

<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.

■ 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.

40
 BulkSMS API Documentation

● 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
verify bulkpush.mytoday.com's signature. That is "If I trust Digicert, I can trust mytoday.com".

41
 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

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.

42
 BulkSMS API Documentation

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

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

43
 BulkSMS API Documentation

You get the status as-

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

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.

44
 BulkSMS API Documentation

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 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

45
 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.

● 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:

46
 BulkSMS API Documentation

○ 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 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.

47
 BulkSMS API Documentation

● 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 dropped.

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

48