API Guide V1.02 Updated 8 Dec 2010 by wuxiangyu


									   API Guide V1.02

Updated 8 Dec 20101
This document provides an overview of the Msg2Send SMS Integration via HTTP.

The technical integration will allow the sending of SMS Messages through HTTP API.

     Msg2Send Account ( Register at http://www.msg2send.com )
     Sufficient Credits in your account.

The Msg2Send API accepts both HTTP GET and POST request at the following URL


Parameter        Required /         Value/Pattern               Sample               Description
Name             Optional

id               Required           Alphanumeric                Test1                Msg2Send user ID

pw               Required           Alphanumeric                Test1                Msg2Send Password

dnr              Required           \+[countrycode][prefix][0   +6512345678          Mobile number to send SMS
                                                                                     message to

senderid         Required           numeric: international      Testing              Originator of the message

                                    \+[0-9]+ national [0-9]+                         (SenderID created and
                                                                                     approved at Msg2Send)
                                    alphanumeric up to 11


msg              Required           Text ISO-8859-1             This is a test       SMS Text Message

flash            Optional           0 or 1                      0                    Flash SMS

send_time        Optional           DDMMYYHHMI                  1205011259           Time to send message

tagid            Optional           [a-zA-Z0-9]+ up to 32       Key123               32 Alphanumeric ID to
                                                                                     uniquely identify the

                                                                                     (Will be provided at Delivery
                                                                                     Report to identify message)

wappush         Optional          0 or 1                          0                    Used to send WAP Push URL
                                                                                       to user instead of text

                                                                                       0 – No Wap Push(Default)
                                                                                       1 – Wap Push Required

encoding        Optional          0 or 1                          0                    Used to indicate UCS

                                                                                       0 – Latin (Default)
                                                                                       1 - UCS

The msg parameter must be included in the text you want to send.


The previous example sends the message: “This is a test” to the following number +6512345678 with
the originating number Testing together.

Support for long messages (>160 characters)

It is also possible for the client application to submit a message longer than 160 characters, the
message will be split automatically into several SMS and send out as concatenated text messages. If
the receiving phone is able to handle long messages, it will show the text as a single SMS.

Encrypted password

Instead of the sending the password in clear text, you have also the option to submit it encrypted as a
This hash-value does not only contain the password, but also the parameter snr, dnr and msg.
The hash-value must be calculated using the following equation: md5(md5($pw) + $senderid + $dnr +
$msg). ‘+’ meaning concatenated text, for example in php it will be md5(md5($pw) . $senderid .
$dnr . $msg)

Sending Wap Push

If wap push parameter is set to 1, the title and url of the wap push must be in the following format in
the msg parameter.

Format for msg: Title,url
Example: msg=msg2send,http://wap.example.com
Sample url:
msg= msg2send,http://wap.example.com&wappush=1

UCS encoded text messages

You can submit messages containing foreign (non-latin) characters using the Unicode Character Set
(UCS) Encoding, to use this feature you have to add the parameter encoding with the value 1 to your
request and you have to encode your text according to UCS.

You can find a complete list of UCS-characters at


http:// api.msg2send.com/api?id=test1&pw=test1&dnr=%2B46512345678&senderid=%2BTesting

This example sends the Russian text (with Cyrillic letters) “this is a test“.

Program Example

  Example code for sending SMS through HTTP2SMS.
  /* Variables together with the values to be transferred. */
  $dnr=”+6512345678”; /* number of destination */
  $senderid=”testing”; /* senderid */
  $msg=” This is a test “; /* SMS text */
  /* production of the required URL */
  $url = “http://api.msg2send/api?”
  . “id=”. UrlEncode($id)
  . “&pw=” . UrlEncode($pw)
  . “&dnr=” . UrlEncode($dnr)
  . “&senderid=” . UrlEncode($senderid)
  . “&msg=” . UrlEncode($msg);
  /* invocation of URL*/
  if (($f = @fopen($url, “r”)))
  $answer = fgets($f, 255);
  if (substr($answer, 0, 1) == “+”)
  echo “SMS to $dnr transport successful.”;

  echo “an error has occured: \”$answer\”.”;





  echo “Error: URLcould not be opened.”;




 Response Code                                       Description

 +OK 01 message queued (dest=+6512345678)            SMS was successfully delivery through the
                                                     Msg2Send System

 -ERR 52 invalid destination number                  Receiver number has an invalid figure

 -ERR 53 invalid source number                       Forwarding number has an invalid figure

 -ERR 54 invalid user-id                             Invalid user ID and password

 -ERR 55 invalid sender ID or pending approval       Your sender id is invalid or not approved yet.

 -ERR 60 sorry, account has no credit                Account has not enough credit, please recharge

 -ERR Invalid Fields                                 One of the required fields is empty

Users will be able to configure their API URL in their Msg2Send account settings.

Go to Account -> API Access to configure the callback URL. Delivery report will be sent to the specified
URL in HTTP GET request.

The following parameters will be sent to the URL.

 idmessages (message id of the message sent out)
 dnr (destination mobile number)
 status (actual status of the SMS: 0 = successfully delivered, 1 = requeued for some reason, 2 =
  delivery failed) See Appendix A for status code
 reason (detailed error code if status = 1 or 2)) See Appendix B for reason code
 mnc(mobile network code in dec. form, e.g. “02” for V/G. Multiple mnc are comma separated.
  Returns “0” forunknown network)
 mcc(mobile country code in dec. form, e.g. “262” for Germany. Returns “0” for unknown country
 tagid (unique 32 alphanumeric code to tag your messages)


Value   Description

-1      SMS is queued at the Msg2Send System

0       SMS Successfully Delivered

1       SMS is buffered

2       SMS Delivery Failed (see reason code for detailed reason)

3       SMS has been successfully submitted but have yet to received a delivery report


Value   Description

0       Unknown subscriber MSISDN

1-8     Service temporary not available

9       Invalid error code

100     Network time-out

101     Destination network is not supported

102     Unknown subscriber MSISDN

103     Destination network is not supported

104     Call barred – delivery blocked to the MSISDN

        from the MNO

105     Operation barred from the MNO

106     SC congestion – delay in the Service-Centre

107     Destination network is not supported

108     Absent subscriber – Handset switched off or

        outside the home network. Retry of SMS delivery

        if handset is on again or deleted after expiry of


109     Delivery fail – SMS cannot be delivered due to a

        temporary error. Further retries until expiry of


110     Protocol error – Error in data communication with

        the handset

111     MS not equipped – Handset not able to receive


112     Unknown SC – unknown service center

113     SC congestion – congestion in the Service


114     Illegal MS – Recipient cannot be reached

        through this service center

115     MS not a subscriber - Recipient cannot be

        reached through this service center

116     Error in MS – Error on the handset

117   SMS lower layer not provisioned – SMS delivery

      not supported

118   System fail – Error in the destination network

119   PLMN system failure – Error in the PLMN: public

      land mobile network

120   HLR system failure – Error in querying the HLR

      (Home location register)

121   VLR system failure – temporary error in the

      visitor location register data base. SMS retries

      will be performed until delivery was successful or

      until end of SMS validity

122   Previous VLR system failure – see 121

123   Controlling MSC system failure – error in the

      MSC = mobile switching center, in the area

      where the user is located

124   VMSC system failure – (Visited Mobile Switching


125   EIR system failure (EIR = equipment identity


126   System failure - Service temporary not available

127   Unexpected data value

159   MNP other operator not allowed – The MSISDN

      is ported, therefore the delivery via this SMS is

      not permitted

160   Subscriber temp. unreachable while roaming

161   Subscriber busy for MT – Subscriber is currently

      receiving SMS from another SMSC

162   No reply from MS on page request – Device is

      not responding on MT request (temp out of

      reach, or switched off)

200   Error in address service centre

201   Invalid absolute Validity Period (e.g. SMS validity

      in the past)

202   Short message exceeds maximum length

203   Unable to Unpack GSM message

204   Unable to convert to IA5 ALPHABET

205   Invalid validity period format – please check the


206   Invalid destination address – MSISDN was

      rejected by the operator

207   Duplicate message submit

208   Invalid message type indicator

512   Expired – Message expired

513   Rejected – Message rejected

514   Retry queue – Delivery retry

515   No route to destination

516   Buffered in SMSC for unknown reason

517   SMS blocked due to spam policy

518   Destination not allowed – SMS has not been

      delivered, because account is not enabled for

      this destination.

601   Message length is invalid

602   Command length is invalid

603   Invalid command ID

604   Incorrect bind status

605   ESME already in bound state

606   Invalid priority flag

607   Invalid registered delivery flag

608   System error

610   Invalid source address (sender-ID)

611   Invalid destination address

612   Invalid message ID

613   Bind failed

614   Invalid password

615   Invalid system ID

617   Cancel SM failed – Cancel of an existing SMS


619   Replace SM failed – Replace of an existing SMS


620         Message queue full

621         Invalid service type

622 – 627   MT billing Services

649         Param Retrieve Failed – Parameter could not be


650         Invalid Param

651         Invalid number of destinations

664         Destination flag is invalid (sm_multi)

666         Submit w/replace invalid – replacement of

            existing SMS rejected

667         ESM Class is invalid

668         Cannot submit to DL (Distribution list)

669         Submit SM/Multi failed – Submit to multiple

            recipient rejected

672         Invalid Source TON

673         Invalid Source NPI

674         Invalid System Type

675         Invalid Replace if present flag

676         Invalid number of messages

688         I/F Throttled Error

691         Invalid Scheduled Delivery Time

692         Expiry/Validity period is invalid

693         Predefined Message Not Found

697         Query SM Failed

855         Unknown Error


To top