Get SMS Delivery Status

Request endpoint: https://api.cosmicsms.com/prod/rest/sms/status/{batch_id}

Get the delivery status for submitted messages. Returns the message delivery status for the 1 or more recipient mobile numbers associated with the specified batch id. The batch id is sourced from the XML response when an SMS message is submitted for delivery as described in section 3.3

HTTP Header Values

Request Endpoint Path Values

Get SMS Delivery Status Example

Below is an example of how to get the delivery status for an SMS message batch using Curl:

curl -k https://api.cosmicsms.com/prod/rest/sms/status/12345678 -X GET -H "Authorization: Basic R2VvZmZyZXk6QWJDMTIzRGVGNDU2"

Note: The above example will return ‘401 Unauthorised’ so the Authorization header value needs to be replaced with valid authentication credentials, and a valid batch number needs to be set

XML Response Parameters

Response Status Values

The message delivery status is returned in the XML response parameter

<statusid>.

Get Account Balance

Request endpoint: https://api.cosmicsms.com/prod/rest/account/balance

Retrieve the current account balance using the HTTP GET method.

HTTP Header Values

Get Account Balance Example

Here is an example of how to retrieve your account balance using Curl:

curl -k https://api.cosmicsms.com/prod/rest/account/balance -X GET -H "Authorization: Basic UGhpbFRlc3QyOmY1NjI3MzLTRjNg=="

Note: The above example will return ‘401 Unauthorised’ as the Authorization header value needs to be replaced with valid authentication credentials.

XML Response Parameters

Response Status Values

XML Response Example

<?xml version="1.0" encoding="UTF-8" ?> <getbalance> <balance>65.82</balance> <currency>GBP</currency> </getbalance>

Character Sets and Encodings

The GSM-7 and Unicode character encoding standards are supported for sending SMS text messages. GSM-7 defines the standard alphabet which is mandatory for mobile networks and GSM mobile handsets (all mobile phones with a SIM card). Unicode is implemented at the mobile network level as UCS-2 and enables the transmission of a broader range of languages and richer content to mobile phones.

The character encoding you should use depends on the language and symbols you need to send in the SMS message. The character encoding used also dictates the maximum length of a SMS text message and therefore can also affect the cost of an SMS message

GSM-7 is the default character encoding used, if unspecified in the API request.

GSM-7

GSM-7 is the standard character set for sending SMS messages and is supported on GSM networks and mobile handsets globally. It contains the more commonly used letters, accented forms and symbols and is suitable for English and most West-European languages.

Each GSM-7 character uses 7-bits. A standard GSM-7 message contains up to 140 bytes, which translates to 160 characters (140*8)/7 = 160.

GSM-7 Character Set

GSM-7 Character Set - Extended

The GSM-7 standard also defines an extended character set containing the following characters:

{ } \ ~ [ ] | ^ €

These are transmitted to the mobile handset in an escaped format, and consequently use 2 7-bit characters each instead of 1.

Multi-Lingual

With the ‘multilingual’ option enabled, messages are sent using the Unicode standard which allows for a much wider range of characters to be sent that are not available in the GSM-7 character set.

Each Unicode character uses 2 bytes (16 bits). A standard Unicode message contains up to 140 8-bit octets, which translates to 70 characters (140*8)/16 = 70.

The full list of Unicode characters can be found here.

Unicode – Pros and Cons

Pros: The Unicode character set is used for Multi-Lingual messages and supports a huge range of characters not available in the GSM-7 character set. This includes non-Latin alphabets such as Chinese, Russian and Arabic, mathematical and technical symbols and emoji.

Cons: Unicode characters are sent to the mobile handset using 2 bytes per character, which limits the length of a (non-concatenated) Unicode message to 70 characters. The maximum message length for a (non-concatenated) GSM-7 message is 160 characters. SMS messages are charged on a per message basis so this can have cost implications.

Both Unicode and GSM-7 messages can be sent as concatenated multi-part SMS messages which are displayed on the recipient mobile handset as a single long SMS message. Concatenated SMS messages are explained further in Section 7.

XML Special Characters

The following characters should be represented in the message field as XML entity values so they do not interact with the syntax of the XML mark-up.

Concatenated SMS Messages

If an SMS message exceeds the single message length of 160 characters for a GSM-7 message or 70 characters for a Unicode message, it is split into smaller parts, which are then sent as individual messages, each with a 6 byte user data header (UDH) that contains the information the recipient phone requires to re-order the message parts correctly and display as a single message. The required addition of the 6 byte UDH for messages exceeding the standard length is the reason for the slightly reduced length of the subsequent message parts.

The table below illustrates the incremental and total number of characters available for a concatenated message, depending on the character set used