English

Application Programming Interface (SMS API)

Please, make sure to have a look at the How To before you get too deep into anything. Thanks!

Send SMS API

Function: sendSms

Sends GSM and Unicode SMS text messages. Concatenates long messages automatically up to five (765 characters).
Returns a JSON object confirming the request (or stating an error).

POST/GET Example

username=xxx&password=yyyy&function=sendSms &number=+491234567890&message=Have%20a%20nice%20day! &senderid=+44987654321&callbackurl=http://www.my-server.com/callback.php

JSON Example

{
    "username":"xxx",
    "password":"yyy",
    "function":"sendSms",
    "number":"+491234567890",
    "message":"Have a nice day!",
    "senderid":"+449876543210",
    "callbackurl":"http://www.my-server.com/callback.php"
}

Mandatory Parameters

Parameter Description Type
number The cell phone number in international format. For example: 49123456789 or +49123456789 or 0049123456789 string
message The message body. My-Cool-SMS auto-detects the input encoding and processes the SMS accordingly as GSM or Unicode.
You can use the optional Unicode parameter to force a particular encoding. If Unicode is set to true the SMS will be sent as Unicode and the message parameter must be provided in Unicode UCS2 notation. If Unicode is set to false the SMS will be sent as GSM and the message parameter must contain characters from the GSM7 alphabet only.
Long messages are automatically concatenated. Maximum 765 characters for GSM messages or 335 for Unicode.
Please note that you should always use the unicode parameter when sending GET requests.
string
Hint: Find out more about GSM, Unicode and UCS2.

Optional Parameters

Parameter Description Type
unicode Forces Unicode or GSM encoding on the message. If set to true, the message parameter must be submitted in UCS2 notation. If set to false, the message parameter must contain characters from the GSM7 alphabet only.
If not set or set to NULL, My-Cool-SMS will autodetect the input encoding.
boolean
senderid Cell phone number in international format, for example: +44123456789 or alpha‐numeric sender id up to 11 characters, for example: Company string
scheduletime Sends the message at a specific time. Use ATOM format and timezone, i.e.: "2011-04-17T17:59:36.67+08" or "2011-04-17 17:59:36-02" timestamp with timezone
callbackurl Callback URL to receive status updates and delivery reports for this message. For example: http://www.myserver.com/callback.php string
Hint: Find out more about delivery report callbacks.

Success Response Example

{
    "success":true,
    "smsid":"ce184cc0a6d1714d1ac763f4fe89f521",
    "body":"Have a nice day!",
    "bodyucs2":"0048006100760065002000610020006E00690063006500200064",
    "bodygsm7":"486176652061206E6963652064617921",
    "number":"+491234567890"
    "senderid":"+449876543210",
    "senderidenabled":true,
    "unicode":false,
    "numchars":321,
    "escapenumchars":0,
    "smscount":3,
    "charge":0.112,
    "balance":752.121,
    "countrycode":"DE",
    "prefix":"+49",
    "timestamp":"2013-04-02T22:27:22-07:00",
    "callbackurl":"http://www.my-server.com/callback.php"
}

Success Response Values

Key Description Type
success Indicates whether the request could be succesfully processed or not boolean
smsid Unique ID for this SMS. Should be stored on client end and used as reference for delivery reports string(32)
body The message body in Unicode string
bodyucs2 The message body in UCS2 bytecode notation string
bodygsm7 The message body in GSM7 bytecode notation (or NULL if the message was sent as Unicode) string || NULL
senderid Indicates the sender id used for the sent message. string
senderidenabled Indicates whether the destination number supports dynamic sender id boolean
unicode Indicates whether the message was sent as Unicode or GSM boolean
numchars Indicates how many characters the message contained integer
escapenumchars Indicates how many characters needed to be escaped (and counted as two characters in GSM) integer
smscount Indicates whether the message was concatenated into a long SMS and provides the number of SMS used integer
charge Indicates how much your account was charged for this message float
balance Remaining balance in your account float
countrycode Indicates to which country the SMS was sent to (ISO Code) string
prefix Indicates the prefix of the country to which the SMS was sent to string
timestamp Timestamp of when the SMS was accepted (using the time zone you were on when you logged in to the web portal the last time or UTC if unknown). Given in DATE_ATOM Format (e.g. 2013-04-02T22:27:22-07:00). string
callbackurl Callback URL that status updates and delivery reports for this message will be sent to. string || NULL

Function Specific API Errors

Error Code Error Description
210 The number seems to be invalid
211 The message parameter is empty
212 The message parameter is too long
213 The unicode parameter is set to force Unicode but the message parameter was not submitted in UCS2 notation.
214 The unicode parameter is set to force GSM but the message parameter was submitted with UCS2 notation
215 The unicode parameter is set to force GSM but the message parameter contains characters outside the GSM7 alphabet
216 The input for Sender ID is invalid. You may use a phone number or an alphanumeric text with up to eleven characters (A-Z, a-z, 0-9 and the dash symbol).
217 Shortcode Sender IDs are not permitted
218 The callbackurl parameter seems to be invalid
219 The schedule time seems invalid. Use ATOM format and timezone, i.e.: "2011-04-17T17:59:36.67+08" or "2011-04-17 17:59:36-02"
Hint: Also see the section about generic errors

Inbound SMS API

Callback: pushIncomingSms

My-Cool-SMS automatically pushes the SMS data to your server if a callback URL for your number is defined in your inbox settings. You can edit your callback URL in your inbox settings via the My-Cool-SMS web interface.

Callback Example

POST /your/callbackurl.php HTTP/1.1
Content-Type: application/json
Host: www.your-server.com
User-Agent: My-Cool-SMS Incoming SMS Callback
Content-Length: n
Cache-Control: no-cache
Connection: close

{
   "from":"+1230987654321",
   "fromcountrycode":"US",
   "to":"+440987654321",
   "unicode":false,
   "smscount":1,
   "body":"Have a nice day with incoming SMS!",
   "bodyucs2":"0048006100760065002000610020006e00690063006500200064",
   "bodygsm7":"5374616666206D6565746925",
   "numchars":54,
   "escapenumchars":0,
   "cost":"0.010"
}
Hint: Have a look here for more information on how to handle JSON callbacks.

Callback Values

Key Description Type
from The sender id the message was sent with. Can be a number in international format or an alphanumeric sender id. string
fromcountrycode Contains the two character code ISO country code of the sender if the from parameter is a number. Contains NULL if the from parameter is alphanumeric. string(2) || NULL
to The number the message was sent to (your virtual phone number). string
unicode Indicates whether the message was sent in Unicode or GSM. boolean
smscount Indicates whether the message was concatenated into a long SMS and provides the number of SMS used integer
body The message body in Unicode string
bodyucs2 The message body in UCS2 bytecode notation string
bodygsm7 The message body in GSM7 bytecode notation (or NULL if the message was sent as Unicode) string
numchars Indicates how many characters the message contained integer
escapenumchars Indicates how many characters needed to be escaped (and counted as two characters in GSM) integer
cost Indicates how much your account was charged for this message float

Function: getIncomingSms

Queries the server for received SMS text messages. Returns a status summary for the selected virtual number and an array containing inbound SMS. Can be customized by using the optional parameters.

POST/GET Example

username=xxx&password=yyy&function=getIncomingSms&virtualnumber=+449876543201

JSON Example

{
    "username":"xxx",
    "password":"yyy",
    "function":"getIncomingSms",
    "virtualnumber":"+449876543201"
}

Mandatory Parameters

Parameter Description Type

Optional Parameters

Parameter Description Type
thresholdid Only messages with a higher id should be returned. This parameter is required to only receive messages that have been received after the ones that were fetched already. Every message fetched with the getIncomingSms function contains a unique id, which should be stored on client side in order to use it here. Defaults to 0. integer
limit The maximum amount of messages to be returned. Defaults to 25. If set to 0, no limit will be applied. integer
order Specifies the order in which the results should be returned. Can be "ASC" or "DESC". Defaults to "DESC" string
thresholdoperator Specifies whether the returned messages should have higher or lower ids as compared to the id provided in thresholdid. Can be either "gt" (greater than) or "lt" (lower than). Defaults to "gt" string(2)
virtualnumber The virtual number for which sms text messages should be fetched. If no virtual number is provided inbound texts for all virtual numbers will be returned. string
unreadsmstosyncids This parameter is useful if you want to sync the read/unread status of your inbound SMS pipe on several devices. Provide the ids of the messages that are marked as unread on your device to receive a list of ids of messages that have been marked as read on a different device. You can use those ids to update the read/unread status on your device. If no messages were marked as read the list will be empty. array[int]

Success Response Example

{
   "success":true,
   "total":"17",
   "fetched":1,
   "maxid":201,
   "minid":177,
   "messages":[
      {
         "id":201,
         "virtualnumber":"+449876543201",
         "senderid":"+886983029751",
         "body":"Have a nice day!",
         "bodyucs2":"AAAA",
         "bodygsm7":"AA",
         "unicode":false,
         "timestamp":"2011-08-10 00:08:37.488+08",
         "unixtimestamp":"1316531343.9",
         "numchars":16,
         "escapechars":0,
         "smscount":1,
         "charge":"0.015",
         "senderidcountrycode":"TW",
         "virtualnumbercountrycode":"HK"
      }
   ]
}

Success Response Values

Key Description Type
success Indicates whether the request could be succesfully processed or not boolean
total The total number of messages on this virtual number integer
fetched The number of messages that were fetched integer
maxid The "maxid" parameter indicates the highest unique id (last message) on this virtual number. This value should be stored and use for future queries as "thresholdid" parameter in order to just fetch new messages. integer
minid The lowest sms id found for this user. Can be used for client side reference. integer
messages Contains an array of SMS text objects (with self-explaining attribute names, see example). array

Function Specific API Errors

Error Code Error Description
232 The number seems to be invalid
233 The virtual number is either invalid or not registered with this user account. Please contact service@my-cool-sms.com for assistance.
234 The provided thresholdid is invalid
235 Invalid limit parameter
236 Invalid order parameter
242 No virtual numbers found.
Hint: Also see the section about generic errors

Balance Lookup API

Function: getBalance

Returns a JSON object containing the remaining balance in your account (or stating an error).

POST/GET Example

username=xxx&password=yyyy&function=getBalance

JSON Example

{
    "username":"xxx",
    "password":"yyy",
    "function":"getBalance"
}

Success Response Example

{
    "success":true,
    "balance":752.210
}

Success Response Values

Key Description Type
success Indicates whether the request could be succesfully processed or not boolean
balance Remaining balance in Euro float

Delivery Report API

There is two ways to receive delivery reports from My-Cool-SMS. You can poll the My-Cool-SMS server with getDeliveryReport or receive HTTP callbacks on a URL on your server with pushDeliveryReport. Please note that delivery reports for mailings are only available via getDeliveryReport.

Function: getDeliveryReport

Returns a delivery report for a single SMS (sent with sendSms) or a group mailing (sent with sendMailing). If a group mailing delivery report is requested (by setting the optional groupkey parameter to true), the return object can contain a summary (default) or individual delivery reports for every single recipient (by setting the optional parameter mailingdetails to true)

POST/GET Example

username=xxx&password=yyyy&function=getDeliveryReport &id=ce184cc0a6d1714d1ac763f4fe89f521

JSON Example

{
    "username":"xxx",
    "password":"yyy",
    "function":"getDeliveryReport",
    "id":"ce184cc0a6d1714d1ac763f4fe89f521"
}

Mandatory Parameters

Parameter Description Type
id Reference ID. Either an sms id (as returned by sendSms) or a mailing group key (as returned by sendMailing).
If a group key is used, the optional parameter groupkey must be set to true.
string

Optional Parameters

Parameter Description Type
groupkey Set to true if a group key was provided in the id parameter and you want the delivery report for a mailing (instead of a single SMS) to be returned. Defaults to false. string
mailingdetails Set to true if you want a seperate delivery report for every recipient of a mailing additionally to the summary. Defaults to false. string

Success Response Example: groupkey=false (Default)

{
    "success":true,
    "smsid":"ce184cc0a6d1714d1ac763f4fe89f521",
    "status":"SMS_STATUS_DELIVERED"
}

Success Response Values: groupkey=false (Default)

Key Description Type
success Indicates whether the request could be succesfully processed or not boolean
smsid The sms id the delivery report is associated with string
status Indicates the status of this SMS string
Hint: Have a look here for more information on status codes.

Success Response Example: groupkey=true

{
    "success":true,
    "groupkey":"d3743cc0a6d1714d1ac763f4fe89f521",
    "total":12,
    "SMS_STATUS_QUEUED":0,
    "SMS_STATUS_AT_CARRIER":0,
    "SMS_STATUS_DELIVERED":12,
    "SMS_STATUS_BOUNCED":0,
    "SMS_STATUS_ERROR":0
}
Hint: Have a look here for more information on status codes.

Success Response Example: groupkey=true&mailingdetails=true

{
    "success":true,
    "groupkey":"d3743cc0a6d1714d1ac763f4fe89f521",
    "total":12,
    "SMS_STATUS_QUEUED":0,
    "SMS_STATUS_AT_CARRIER":0,
    "SMS_STATUS_DELIVERED":12,
    "SMS_STATUS_BOUNCED":0,
    "SMS_STATUS_ERROR":0,
    "details":[
        {
            "recipient":"+1230987654321",
            "status":"SMS_STATUS_DELIVERED"
        },
        {
            "recipient":"+1230987654322",
            "status":"SMS_STATUS_DELIVERED"
        }, 
        (...)
    ]
}
Hint: Have a look here for more information on status codes.

Function Specific API Errors

Error Code Error Description
223 Unknown SMS ID
224 Unknown Group Key
Hint: Also see the section about generic errors

Function: getDeliveryReports

Returns delivery reports for a list of messages.

JSON Example

{
    "username":"xxx",
    "password":"yyy",
    "function":"getDeliveryReports",
    "ids":[
        "ce184cc0a6d1714d1ac763f4fe89f521",
        "d1ac763f4fe89f521ce184cc0a6d1714"
    ]
}

Mandatory Parameters

Parameter Description Type
ids An array of sms ids to perform the delivery status lookup for. array[]

Success Response Example:

{
    "success":true,
    "reports": [
        {
            "smsid":"ce184cc0a6d1714d1ac763f4fe89f521",
            "status":"SMS_STATUS_DELIVERED"
        },
        {
            "smsid":"d1ac763f4fe89f521ce184cc0a6d1714",
            "status":"SMS_STATUS_DELIVERED"
        }
    ]
}

Success Response Values:

Key Description Type
success Indicates whether the request could be succesfully processed or not boolean
reports[] Contains an array with delivery report objects. Each object contains the reference id (smsid) and the corresponding delivery status (status). array
reports[n].smsid Contains the reference sms id for this delivery report string
reports[n].status Contains the delivery status for this SMS. Possible states are: SMS_STATUS_QUEUED, SMS_STATUS_AT_CARRIER, SMS_STATUS_DELIVERY_DELAYED, SMS_STATUS_DELIVERED, SMS_STATUS_BOUNCED, SMS_STATUS_EXPIRED, SMS_STATUS_ERROR or UNKNOWN_ID. string
Hint: Have a look here for more information on status codes.

Function Specific API Errors

Error Code Error Description
240 The input for the "ids" parameter seems invalid. Please make sure to provide an array with valid sms ids.
241 The maximum number of delivery reports per request is 100.
Hint: Also see the section about generic errors

Function: getRecentReports

Returns a JSON object with delivery reports for the most recently sent messages.

POST/GET Example

username=xxx&password=yyyy&function=getRecentReports&limit=10

JSON Example

{
    "username":"xxx",
    "password":"yyy",
    "function":"getRecentReports",
    "limit":10
}

Mandatory Parameters

Parameter Description Type
limit Indicates how many reports should be returned integer

Success Response Example

{
   "success":true,
   "reports":[
      {
         "number":"+1230987654321",
         "senderid":"+449876543210",
         "body":"Have a nice day!",
         "bodyucs2":"0048006100760065002000610020006E006900630065002",
         "bodygsm7":"486176652061206E6963652064617921",
         "unicode":false,
         "timesent":"2011-04-19 12:08:37.233+08",
         "status":"SMS_STATUS_DELIVERED"
      },
      {
         "number":"+1230987654321",
         "senderid":"+449876543210",
         "body":"Have a nice day!",
         "bodyucs2":"0048006100760065002000610020006E006900630065002",
         "bodygsm7":"486176652061206E6963652064617921",
         "unicode":false,
         "timesent":"2011-04-19 12:01:03.338+08",
         "status":"SMS_STATUS_DELIVERED"
      },
      {
         "number":"+1230987654321",
         "senderid":"+449876543210",
         "body":"Have a nice day with long Unicode messages! \u7e41",
         "bodyucs2":"0048006100760065002000610020006e00690063006500",
         "bodygsm7":"",
         "unicode":true,
         "timesent":"2011-04-18 21:53:24.787+08",
         "status":"SMS_STATUS_DELIVERED"
      },
      (...)
   ]
}

Success Response Values

Key Description Type
success Indicates whether the request could be succesfully processed or not boolean
number The destination number string
senderid The sender id the message was sent with string
body The message body in Unicode string
bodyucs2 The message body in UCS2 bytecode notation string
bodygsm7 The message body in GSM7 bytecode notation (or NULL if the message was sent as Unicode) string
unicode Indicates whether the message was sent as Unicode or GSM boolean
timesent Time at which the message was sent timestamp with time zone
status Indicates the status of this SMS string
Hint: Have a look here for more information on status codes.

Function Specific API Errors

Error Code Error Description
225 Invalid limit parameter
Hint: Also see the section about generic errors

Callback: pushDeliveryReport

My-Cool-SMS automatically pushes a delivery report to your server if the callbackurl parameter is set when sending via the sendSms function. The callback is sent as raw data JSON request.

Callback Example

POST /your/callbackurl.php HTTP/1.1
Content-Type: application/json
Host: www.your-server.com
User-Agent: My-Cool-SMS Delivery Report
Content-Length: n
Cache-Control: no-cache
Connection: close

{
    "smsid":"498673a1f58df975ab95da33884d9e14",
    "status":"SMS_STATUS_DELIVERED"
}
Hint: Have a look here for more information on how to handle JSON callbacks.

Callback Values

Key Description Type
smsid Unique ID and reference for the SMS. The smsid was returned in the success response on the sendSms function string(32)
status Indicates the status of this SMS string

Status Reference

Status Description
SMS_STATUS_QUEUED Queued - This message is currently queued and has not been sent yet.
SMS_STATUS_AT_CARRIER At Carrier - The message has been sent to the network provider and should show as 'delivered' as soon as it arrives on the target phone.
Please note that in some instances carriers will not provide a delivery report. The message will remain being displayed as 'at carrier' then although it has been successfully delivered.
SMS_STATUS_DELIVERY_DELAYED Delivery Delayed - The message delivery was delayed
SMS_STATUS_DELIVERED Delivered - The message was succesfully delivered to the target number
SMS_STATUS_BOUNCED Bounced - The message has been bounced by the target network. Possible reasons are an invalid cell phone number or sender id, the target phone being out of network reach for too long or network congestions on carrier level.
SMS_STATUS_EXPIRED Expired - This message has expired and could not be delivered.
This problem usually happens if the target cell phone has been switched off or out of network reach for a long period of time.
SMS_STATUS_ERROR Failed - Delivery has failed (you have not been charged for this message).
Possible reasons for failed delivery are My-Cool-SMS not knowing which network the phone number belongs to (please contact support if you are positive that the phone number is correct) or a temporary network error.

Function: getOutboundSms

This function is useful if you want to sync the outbound SMS streams in your account for different devices. It queries the server for outbound sms data and returns and array delivery statuses and additional information on the messages, such as content and timestamps.

POST/GET Example

username=xxx&password=yyy&function=getOutboundSms

JSON Example

{
    "username":"xxx",
    "password":"yyy",
    "function":"getOutboundSms"
}

Mandatory Parameters

Parameter Description Type

Optional Parameters

Parameter Description Type
thresholdid Use this parameter to specify the particular message for which you would like to check if messages were sent before or after. Combine with the thresholdoperator parameter to specify if you need messages with lower or greater ids. string(32)
limit The maximum amount of messages to be returned. Defaults to 25. integer
thresholdoperator Specifies whether the returned messages should have higher or lower ids as compared to the id provided in thresholdid. Can be either "gt" (greater than) or "lt" (lower than). Defaults to "gt" string
order Specifies the order in which the results should be returned. Can be "ASC" or "DESC". Defaults to "DESC" string

Success Response Example

{
   "success":true,
   "total":"17",
   "fetched":1,
   "maxid":201,
   "minid":177,
   "messages":[
      {
        "smsid":"ce184cc0a6d1714d1ac763f4fe89f521",
        "body":"Have a nice day!",
        "bodyucs2":"0048006100760065002000610020006E00690063006500200064",
        "bodygsm7":"486176652061206E6963652064617921",
        "number":"+491234567890"
        "senderid":"+449876543210",
        "senderidenabled":"+449876543210",
        "unicode":false,
        "numchars":321,
        "escapenumchars":0,
        "smscount":3,
        "charge":0.112,
        "countrycode":"DE",
        "prefix":"+49",
        "timestamp":"2013-04-02T22:27:22-07:00",
        "callbackurl":"http://www.my-server.com/callback.php",
        "status":"SMS_STATUS_DELIVERED"
      }
   ]
}

Success Response Values

Key Description Type
success Indicates whether the request could be succesfully processed or not boolean
total The total number of SMS sent on this account. integer
fetched The total number of SMS returned by this query. integer
maxid Indicates the newest sms returned by this query. Can be used as new thresholdoperator parameter in a subsequent API call. integer
minid Indicates the oldest sms returned by this query. Can be used as new thresholdoperator parameter in a subsequent API call. integer
messages An array containing objects with the outbound SMS returned by this query. The SMS object attributes correspond to the return values of the sendSms function (please see that section for details). array

Function Specific API Errors

Error Code Error Description
234 The provided thresholdid is invalid
235 Invalid limit parameter
236 Invalid order parameter
Hint: Also see the section about generic errors

Mailing List API

Function: sendMailing

Sends an SMS to an entire mailing list. Hint: You can create and manage mailing lists in your My-Cool-SMS web interface.
Returns a JSON object confirming the request (or stating an error).

POST/GET Example

username=xxx&password=yyyy&function=sendMailing &uniqueid=75F3FAB&message=Staff%20meeting%20in%2020%20minutes. &senderid=MyCompany

JSON Example

{
    "username":"xxx",
    "password":"yyy",
    "function":"sendMailing",
    "uniqueid":"75F3FAB",
    "message":"Staff meeting in 20 minutes. Balcony meeting room.",
    "senderid":"MyCompany"
}

Mandatory Parameters

Parameter Description Type
uniqueid The mailing list's unique id. You'll find the your unique ids in your mailing list management interfaces on the web site. string
message The message body. My-Cool-SMS auto-detects the input encoding and processes the SMS accordingly as GSM or Unicode.
You can use the optional Unicode parameter to force a particular encoding. If Unicode is set to true the SMS will be sent as Unicode and the message parameter must be provided in Unicode UCS2 notation. If Unicode is set to false the SMS will be sent as GSM and the message parameter must contain characters from the GSM7 alphabet only.
Long messages are automatically concatenated. Maximum 765 characters for GSM messages or 335 for Unicode.
Please note that you should always use the unicode parameter when sending GET requests.
string
Hint: Find out more about GSM, Unicode and UCS2.

Optional Parameters

Parameter Description Type
unicode Forces Unicode or GSM encoding on the message. If set to true, the message parameter must be submitted in UCS2 notation. If set to false, the message parameter must contain characters from the GSM7 alphabet only.
If not set or set to NULL, My-Cool-SMS will autodetect the input encoding.
boolean
senderid Cell phone number in international format, for example: +44123456789 or alpha‐numeric sender id up to 11 characters, for example: Company string
scheduletime Sends the message at a specific time. Use ATOM format and timezone, i.e.: "2011-04-17T17:59:36.67+08" or "2011-04-17 17:59:36-02" timestamp with time zone
Hint: Find out more about delivery report callbacks.

Success Response Example

{
    "success":true,
    "groupkey":"041d3b026a50669481695dcf9e1985e4",
    "body":"Staff meeting in 20 minutes. Balcony meeting room.",
    "bodyucs2":"005300740061006600660020006D0065006500740069",
    "bodygsm7":"5374616666206D656574696E672069",
    "uniqueid":"75F3FAB"
    "senderid":"MyCompany",
    "senderidenabled":true,
    "unicode":false,
    "numchars":62,
    "escapenumchars":0,
    "smscount":1,
    "subscribers":79,
    "charge":3.212,
    "balance":752.121
}

Success Response Values

Key Description Type
success Indicates whether the request could be succesfully processed or not boolean
groupkey Unique reference key for this mailing. Should be stored on client end and used as reference for delivery reports string(32)
body The message body in Unicode string
bodyucs2 The message body in UCS2 bytecode notation string
bodygsm7 The message body in GSM7 bytecode notation (or NULL if the message was sent as Unicode) string || NULL
uniqueid string(7)
senderid Indicates whether the destination number supports dynamic sender id boolean
unicode Indicates whether the message was sent as Unicode or GSM boolean
numchars Indicates how many characters the message contained integer
escapenumchars Indicates how many characters needed to be escaped (and counted as two characters in GSM) integer
smscount Indicates whether the message was concatenated into a long SMS and provides the number of SMS used integer
subscribers Number of subscribers the message was sent to integer
charge Indicates how much your account was charged for this message float
balance Remaining balance in your account float

Function Specific API Errors

Error Code Error Description
220 The unique id is not associated with any of your mailing lists
Hint: Also see the section about generic errors

Function: addSubscriber

Inserts a new subscriber to the mailing list. Updates a subscriber if the submitted number already exists in the target mailing list.
Returns a JSON object confirming the request (or stating an error).

POST/GET Example

username=xxx&password=yyyy&function=addSubscriber &uniqueid=75F3FAB&number=+1230987654321&title=Ms&firstname=Marylin &lastname=Monroe&company=Hollywood

JSON Example

{
    "username":"xxx",
    "password":"yyy",
    "function":"addSubscriber",
    "uniqueid":"75F3FAB",
    "number":"+1230987654321",
    "title":"Ms",
    "firstname":"Marylin",
    "lastname":"Monroe",
    "company":"Hollywood"
}

Mandatory Parameters

Parameter Description Type
number The subscriber's number in international format. For example: 49123456789 or +49123456789 or 0049123456789 string
uniqueid The mailing list's unique id. You'll find the your unique ids in your mailing list management interfaces on the web site. string

Optional Parameters

Parameter Description Type
title The subscriber's title varchar(16)
firstname The subscriber's first name varchar(32)
lastname The subscriber's last name varchar(32)
company The subscriber's company varchar(64)

Success Response Example

{
    "success":true,
    "number":"+1230987654321"
    "title":"Ms",
    "firstname":"Marylin",
    "lastname":"Monroe",
    "company":"Hollywood",
    "subscribercost":0.019,
    "senderidenabled":true,
    "maxcharsgsm":765,
    "maxcharsunicode":335,
    "countrycode":"US",
    "mailinglistcost":1.213
    "mailinglistsubscribers":74
}

Success Response Values

Key Description Type
success Indicates whether the request could be succesfully processed or not boolean
number Normalized phone number of the new subscriber string
title Title of the new subscriber string
firstname First name of the new subscriber string
lastname Last name of the new subscriber string
company Company of the new subscriber string
subscribercost Cost per message to this subscriber float
senderidenabled Indicates whether the subscriber supports sender id boolean
maxcharsgsm Indicates how many characters the subscriber supports for GSM messages integer
maxcharsunicode Indicates how many characters the subscriber supports for Unicode messages integer
countrycode The subscribers country code (Two letter ISO stanard format) string(2)
mailinglistcost The new total cost for mailings to this list float
mailinglistsubscribers The new number of subscribers on this mailing list integer

Function Specific API Errors

Error Code Error Description
221 Input for {field} is too long.
Hint: Also see the section about generic errors

Function: updateSubscriber

See Function: addSubscriber

Function: deleteSubscriber

Removes a subscriber from the mailing list (using the phone number as reference).
Returns a JSON object confirming the request (or stating an error).

POST/GET Example

username=xxx&password=yyyy&function=deleteSubscriber &uniqueid=75F3FAB&number=+1230987654321

JSON Example

{
    "username":"xxx",
    "password":"yyy",
    "function":"deleteSubscriber",
    "uniqueid":"75F3FAB",
    "number":"+1230987654321"
}

Mandatory Parameters

Parameter Description Type
uniqueid The mailing list's unique id. You'll find the your unique ids in your mailing list management interfaces on the web site. string
number The number of the subscriber to delete from the mailinglist string

Success Response Example

{
    "success":true,
    "number":"+1230987654321"
    "mailinglistcost":1.213
    "mailinglistsubscribers":74
}

Success Response Values

Key Description Type
success Indicates whether the request could be succesfully processed or not boolean
number The normalized phone number of the deleted subscriber string
mailinglistcost The new total cost for mailings to this list float
mailinglistsubscribers The new number of subscribers on this mailing list integer

Function Specific API Errors

Error Code Error Description
220 The unique id is not associated with any of your mailing lists
222 There is no subscriber with that phone number on this mailing list
Hint: Also see the section about generic errors

Utils API

Function: doHlrLookup

Performs an Home Location Register (HLR) lookup and returns the number's MSC, MCC, MNC, INSI as well as information on the network name, whether the number is currently roaming and whether it has been ported to another network.
Hint: Find out more about HLR, IMSI, MCC, MNC and MSC.

JSON Example

{
    "username":"xxx",
    "password":"yyy",
    "function":"doHlrLookup",
    "number":"+491234567890"
}

Mandatory Parameters

Parameter Description Type
number The number to perform the HLR Lookup for in international format. For example: 49123456789 or +49123456789 or 0049123456789 string

Success Response Example

{
    "success":true,
    "status":"HLR_STATUS_OK",
    "number":"+49178873xxxxx",
    "imsi":"262031350393955",
    "mcc":"262",
    "mnc":"03",
    "msin":"1350393955",
    "servingmsc":"88693542",
    "servinghlr":"491770112000",
    "originalnetworkname":"E-Plus",
    "originalnetworkprefix":"178",
    "originalcountryname":"Germany",
    "originalcountrycode":"DE",
    "originalcountryprefix":"+49",
    "roamingcountryname":"Taiwan",
    "roamingcountrycode":"TW",
    "roamingcountryprefix":"+886",
    "roamingnetworkname":"Taiwan Mobile",
    "portednetworkname": null,
    "isported":false,
    "iscorrect":true,
    "isroaming":true,
    "charge":0.010
}

Success Response Values

Key Description Type
success Indicates whether the request could be succesfully processed or not boolean
status Indicates the status of the lookup. Please refer to the HLR status reference table for details. string
number The number the HLR lookup was performed for. string
imsi International Mobile Subscriber Identity (IMSI). Unique identification associated with the target number. string
mcc The Mobile Country Code (MCC) string
mnc The Mobile Network Code (MNC), which can be either 2 digits (European Standard) or 3 digits (North American Standard) string
msin The Mobile Subscription Identification Number (MSIN) within the network's customer base. string
servingmsc The Mobile Switching Center (MSC) that is responsible for routing the SMS. string
servinghlr The Home Location Register (HLR) that the target number is associated with. string
originalnetworkname The mobile network this number belongs to (or belonged to originally if this is a ported number) string
originalnetworkprefix The mobile network prefix this number belongs to (or belonged to originally if this is a ported number) string
originalcountryname The country this number belongs to. string
originalcountrycode The two character ISO country code this number belongs to string
originalcountryprefix The prefix of the country this number belongs to string
roamingcountryname The country this number is currently roaming in string
roamingcountrycode The two character ISO country code of the country this number is currently roaming in string
roamingcountryprefix The prefix of the country this number is currently roaming in string
roamingnetworkname The network the cell phone is currently roaming with string
portednetworkname The network the number has been ported to string
isported Indicates whether this is a ported number boolean
iscorrect Indicates whether this number is valid boolean
isroaming Indicates whether this number is currently roaming (in another country) boolean
charge The charge applied for the HLR lookup (0.01 EUR) numeric
Hint: Find out more about HLR, IMSI, MCC, MNC and MSC.

Function Specific API Errors

Error Code Error Description
210 The number seems to be invalid
226 HLR lookup failed. No charge applies.
Hint: Also see the section about generic errors

HLR Status Reference

Status Description
HLR_STATUS_UNKNOWN_NUMBER This number does not exist or couldn't be located in any HLR. SMS will not arrive.
HLR_STATUS_OK This number exists and the HLR lookup was succesful. SMS will arrive.
HLR_STATUS_NOT_OK This number is outside network for a very long time or was disabled by the mobile network provider. SMS will not arrive.
HLR_STATUS_FAILED HLR lookup failed. No charges apply.
HLR_STATUS_AWAITING_RESPONSE Awaiting response from HLR.

Function: toUCS2

UCS2 encodes a given Unicode string
Important: toUCS2 requires a JSON request.

JSON Example

{
    "username":"xxx",
    "password":"yyy",
    "function":"toUCS2",
    "str":"繁体中文"
}

Mandatory Parameters

Parameter Description Type
number The number to perform the HLR Lookup for in international format. For example: 49123456789 or +49123456789 or 0049123456789 string

Optional Parameters

Parameter Description Type

Success Response Example

{
    "success":true,
    "ucs2":"7E414F534E2D6587"
}

Success Response Values

Key Description Type
success Indicates whether the request could be succesfully processed or not boolean
ucs2 The submitted string in UCS2 notation string

Function Specific API Errors

None
Hint: Also see the section about generic errors

Function: fromUCS2

Decodes a given UCS2 string

POST/GET Example

username=xxx&password=yyyy&function=fromUCS2 &str=0048006100760065002000610020006E00690063006500200064

JSON Example

{
    "username":"xxx",
    "password":"yyy",
    "function":"fromUCS2",
    "str":"7E414F534E2D6587"
}

Mandatory Parameters

Parameter Description Type
str The UCS2 string to decode string

Success Response Example

{
    "success":true,
    "decoded":"繁体中文"
}

Success Response Values

Key Description Type
success Indicates whether the request could be succesfully processed or not boolean
decoded The decoded UCS2 string in Unicode string

Function Specific API Errors

Error Code Error Description
201 Invalid UCS2 Input
Hint: Also see the section about generic errors

Function: normalizeNumber

Normalizes a cell phone number in loose format into international standard MSISDN format. For example from +1(712)543-2321 into +17125432321

POST/GET Example

username=xxx&password=yyyy&function=normalizeNumber&number=001(712)736-3423

JSON Example

{
    "username":"xxx",
    "password":"yyy",
    "function":"normalizeNumber",
    "number":"001(712)736-3423"
}

Mandatory Parameters

Parameter Description Type
number The phone number to normalize. Loose format, e.g. 00491787654321, 0049(178)765-4321 etc. string

Success Response Example

{
    "success":true,
    "number":"+17127363423",
    "countrycode":"US"
}

Success Response Values

Key Description Type
success Indicates whether the request could be succesfully processed or not boolean
number The normalized number in international MSISDN standard format. string
countrycode The corresponding country code (international two-character ISO format) string(2)

Function Specific API Errors

Error Code Error Description
237 The number could not be normalized.

Error Responses

All API errors responses have a standardized JSON structure with a success, errorcode and errordescription attribute.

Error Response Example

{
    "success":false,
    "errorcode":103,
    "errordescription":"Mandatory parameter missing: senderid"
}

Error Response Values

Key Description Type
success Indicates whether the request could be succesfully processed or not boolean
errorcode A three digit error code string(3)
errordescription The error description string

Function Specific API Errors

Some functions have specific API errorcodes that are unique to that paticular function. Error codes have the format 2xx in that case. Please refer to the function documentation for individual error codes.

Generic API Errors

Additonally to function specific errors, any request to the API may result in a generic API error with error code format 1xx.

Generic Error Codes

Error Code Error Description
101 Login Failed. Wrong Username or Password.
102 This account has not been activated yet.
103 Mandatory parameter missing
104 Invalid Request. No GET, POST and raw JSON data found. If you are trying to send JSON, please check if it is properly encoded.
105 Unknown Function
106 Permission Denied
107 Generic API Error
108 Invalid request structure
109 Not enough credits
Did we miss something? Do you have questions? Have some advice or something we should add here? If so, let us know!
© My-Cool-Webservices Ltd. 2008-2014
Deutsch
Español
Français
Nederlands
Polski
Português
Руccкий
繁体中文