SMS Gateway
Delivery Reports
Sending an SMS using HTTP
Overview
The MX Telecom SMS Gateway allows SMS messages to be sent using HTTP. This page details the format of the HTTP requests which can be made to the MX Telecom SMS Gateway.
Contents
- Sending an SMS Text Message using HTTP GET
- Parameters for all messages
- Parsing responses to requests
- Plain text messages
- GSM character set messages
- Unicode (UCS-2) messages
- vCard entry
- vCalendar entry
- SMS with UDH
- Data message without UDH
- WAP Push Service Indication
- MMS Notification
- Examples of requests and responses
For details on sending other, less-common message types, please click here.
Sending an SMS Text Message using HTTP GET
The MX Telecom SMS Gateway exposes an HTTP interface allowing applications with internet connectivity to send SMS text messages.
A request for a page using the structure shown below is all that is needed for you to send an SMS through the SMS Gateway. The endpoints for these HTTP requests are http://sms.mxtelecom.com/SMSSend for HTTP and https://sms.mxtelecom.com/SMSSend for HTTPS (SSL).
Messages should be sent as a HTTP GET or POST request using the parameters listed below. One request should be sent per message.
HTTP/1.1 is enabled so, if sending multiple packets, the TCP/IP connection should be kept open between requests. If sending message with a high transmission rate is required, then several persistent HTTP/1.1 connections should be used concurrently (perhaps 3 or 4). Pipelining requests, as in Mozilla, is supported but encouraged only where necessary (i.e. with high message rates and large latency between service provider and MX Telecom).
Parameters for all messages
Several parameters are common to all message types, and should be included in the HTTP request regardless of the specific method being invoked. Details of these parameters are as follows:
| Name | Description |
| user | Username of the account to send through |
| pass | Password |
| smsto | MSISDN of the message recipient (eg 447700900999). No leading "+" is required |
| *smsfrom | Originator for the message (ignored for accounts where changing the originator is not possible). Where valid this can be numeric (maximum 16 digits) or alphanumeric (maximum 11 digits) |
| *note | Note that will be stored in the billing record (maximum 160 characters) |
| *subaccount | Sub account that will be stored in the billing record (maximum 10 characters) |
| *report | Flags for delivery reports (These are bit fields, ie report=7 enabled all reports - default=0): Bit 1 - Enable intermediate delivery reports Bit 2 - Enable success delivery reports Bit 3 - Enable failure delivery reports |
| *vp | Validity period for the message, in seconds |
| *mxbillingsingleshot | Enable single-shot billing for the message. By default, messages are submitted as normal; any non-empty value will enable single-shot billing |
The following example shows the common structure of all HTTP requests understood by the MX Telecom SMS Gateway:
http://sms.mxtelecom.com/SMSSend?Along with these parameters, there are a variety of other parameters which are needed for the message body, depending on your preference for the encoding/content of the message.
Parsing responses to requests
The gateway's response to all requests uses the HTTP response code to indicate whether or not the request was accepted:
| Response Code | Description |
| 200 | The request was accepted. The body of the will contain one or more message IDs. |
| 40x | The request was rejected. The possible reasons for this are outlined below. The request should not be retried. |
| 50x | There was a server error. The request should be retried later. |
The possible reasons for requests being rejected, along with their corresponding HTTP request codes, are:
| Problem | Response Code | Response body |
| Invalid request - eg parameters missing/invalid | 400 Bad Request | Description of problem, eg Required parameter user missing |
| Unknown username/password | 403 Forbidden | Bad username/password |
| Request not from whitelisted IP address | 403 Forbidden | You are not authorized to send messages from that IP address |
| Monthly per-account credit limit exceeded | 403 Forbidden | Credit limit exceeeded |
| Daily per-msisdn limit exceeded | 403 Forbidden | Maximum messages to this MSISDN exceeded |
| MSISDN not on allowed-reverse-billing whitelist | 403 Forbidden | Reverse billing Forbidden for <msisdn> |
| MSISDN on block list | 403 Forbidden | Destination is blacklisted |
Plain text messages
The HTTP request should include the common parameters described above, in addition to the following plain-text-specific parameters:
| Parameter | Description |
| smsmsg | The message text, encoded in the Modified Latin-9 character set (see below). |
| *flash | 0 - No flash (Default) 1 - Flash |
| *split |
0 - Don't split long messages. Messages > 160 characters will be rejected. (Default) 1 - Split messages using "..." (Maximum of 5 messages once split) 2 - SMS Concatenation (w. UDH header) - not supported by all phones (Maximum of 4 messages once split) 3 - Split messages into multiple 160 character messages (Maximum of 5 messages once split) |
The example below shows a typical HTTP request for a message of this sort:
http://sms.mxtelecom.com/SMSSend?A form for this message type can be found here.
Or to send a flash message:
http://sms.mxtelecom.com/SMSSend?An example HTML form for this message type can be found here.
This will send a message from the account of user username, with password mypassword, to recipient number 447700900999, with the originator of the message set to 1234 (this may not always be possible). The message, in this case Hello World must be suitably URL encoded (eg the %20 rather than a space).
Along with these parameters, there are a variety of other parameters which are needed for the message body, depending on your preference for the encoding/content of the message.
Modified Latin-9 Character Set
Messages you submit in modified Latin-9 or GSM 03.38 character sets are sent on by MX Telecom in a character set appropriate to the destination handset. These character sets normally have fewer characters than modified Latin-9 so some characters in the modified Latin-9 set do not have a direct counterpart. In these instances, our system performs a best-guess mapping, for example turning the character ï into i.
You may also submit messages in UCS-2 Unicode which supports a much wider variety of characters than either the modified Latin-9 set or the GSM 03.38 set. MX Telecom sends these messages in UCS-2 Unicode encoding. However, as UCS-2 Unicode is a 16-bit encoding, using it to send SMS messages restricts the maximum number of characters per message to 70.
See our Knowledge Base for more information about the Modified Latin-9 Character Set and the GSM 03.38 Character Set.
GSM character set messages
| Parameter | Description | ||
| smsia5 | The message text, encoded in the GSM 03.38 character set | ||
| *flash |
| ||
| *split | 0 - Don't split long messages. Messages > 160 characters will be rejected. (Default) 1 - Not yet implemented: Split messages using "..." etc. 2 - SMS Concatenation (w. UDH header) - not supported by all phones | ||
| *smsudh | Optional hex encoded User Data Header (can only be used when split=0) |
Unicode (UCS-2) messages
| Parameter | Description | ||
| smsucs2 | The message text as hex encoded UCS-2 | ||
| *flash |
| ||
| *split | 0 - Don't split long messages. Messages > 70 unicode characters will be rejected. (Default) 1 - Not yet implemented: Split messages using "..." etc. 2 - SMS Concatenation (w. UDH header) - not supported by all phones | ||
| *smsudh | Optional hex encoded User Data Header (can only be used when split=0) |
The message content should be sent using a series of UCS-2 16-bit words. For example, the character 三 (the Japenese symbol for the number three) is hex-encoded as 4E09. The example below shows a typical HTTP request for a message of this sort:
http://sms.mxtelecom.com/SMSSend?This will send a message to 447700900999 with the text “γεια!”.
vCard entry
| Parameter | Description |
| vcard_data | The vcard to send |
The example below shows a typical HTTP request for a message of this sort:
http://sms.mxtelecom.com/SMSSend?An example HTML form for this message type can be found here.
vCalendar entry
| Parameter | Description |
| vcalendar_description | Description for the event |
| vcalendar_date_start | Start time |
| vcalendar_date_end | End time |
| vcalendar_audio_alarm | Alarm time |
Time format: yyyyMMddThhmmss y=year, M=month, d=day, h=hour m=minute, s=sec.
The example below shows a typical HTTP request for a message of this sort:
http://sms.mxtelecom.com/SMSSend?An example HTML form for this message type can be found here.
SMS with UDH
| Parameter | Description |
| smsudh | User data header. Encoded into hex |
| *bits | Describes the content of the message body: 7 - 7bit text (eg EMS messages) 8 - 8bit data (eg Nokia SmartMessaging) (Default) 16 - 16bit data (e.g. UCS-2 messages) |
| smsmsg | Body of the message If bits=8 or 16: This parameter is mandatory 8 bit message data. Encoded into hex If bits=7: This parameter is optional The text of the message (ISO-8859-1) |
An example HTML form for this message type can be found here.
Data messages without UDH
| Parameter | Description |
| bits | Describes the content of the message body: 8 - 8bit data (eg Nokia SmartMessaging) (Default) |
| smsmsg | Body of the message encoded into hex |
WAP Push Service Indication
| Parameter | Description |
| pushtype | 0 - Type of WAP Push |
| push_href | This attribute specifies the URI that is used to access the service. If href is empty, or omitted, the SI corresponds to a notification (no service can be initiated). |
| push_action |
This attribute may contain a text string specifying the action to be taken when the SI is received.
|
| *push_siid | This attribute may provide the SI with an identity in order to make it possible to distinguish between different SIs. If this attribute is not specified, its value is considered to be the same as the value of the href attribute. In order avoid conflicts between SIs, it is RECOMMENDED that content developers use an address (e.g. URL) within their control combined with an identifier for the SI as the value for si-id (for example: www.wapforum.org/siid/123 or 123@siid.wapforum.org ). This parameter is required if a push_action of signal-delete is specified. |
| push_siname | Name of the Service Indication |
| *push_siexpires | This attribute may be used to specify the date and time when the SI expires and thereby be automatically deleted or marked as expired . If this attribute is not specified, the SI never expires and is thus not subject to automatic deletion. The representation for this attribute value is the same as the one used for the created attribute. |
| *push_initiator | The name of the initiator of the WAP Push (appears as the originator on some handsets) |
For full details on the WAP 1.2 Push Service Indication see WAP Service Indication Specification.
The example below shows a typical HTTP request for a message of this sort:
http://sms.mxtelecom.com/SMSSend?An example HTML form for this message type can be found here.
MMS Notification
| Parameter | Description |
| mms_transaction_id | Identifies the notification and the subsequent transaction that is closed by the following M-NotifyResp. |
| mms_notification | 1 - Flag as a MMS Notification |
| mms_version | 1.0 - The MMS version number. According to this specification, the version is 1.0. |
| *mms_from | Address of the sender. This must be in the correct format. eg. Mobile Number: +447700900999/TYPE=PLMN or Email Address: Joe User <joe@user.org> |
| *mms_subject | Subject of the message. |
| mms_messageclass | Class of the message:
|
| mms_messagelocation | This field defines the location of the message. |
| mms_expire | Length of time the message will be available (minutes). |
| mms_messagesize | Full size of message in bytes. The value of this header field could be based on approximate calculation,therefore it SHOULD NOT be used as a reason to reject the MMS. |
The example below shows a typical HTTP request for an MMS Notification:
http://sms.mxtelecom.com/SMSSend?An example HTML form for this message type can be found here.
Examples of requests and responses
Example of a successful submission of a single plain text message:
GET /SMSSend?user=username&pass=password&smsfrom=1234&smsto=447700900999 &smsmsg=Hello HTTP/1.1 Host: sms.mxtelecom.com HTTP/1.1 200 OK Date: Wed, 05 Aug 2009 11:05:08 GMT Server: Apache/1.3.26 (Unix) mod_ssl/2.8.8 OpenSSL/0.9.6a Content-Type: text/plain Transfer-Encoding: chunked b 4316310753 0
In the above example, a message is successfully submitted to the gateway with a destination of +447700900999 and an originator of 1234. The message ID was 4316310753. Note that the numbers either side of the message id is present as a result of the "chunked" transfer-encoding and will be stripped out by a browser or other transfer agent.
Example of a successful submission of a multi-part message (containing a nokia operator logo):
GET /SMSSend?user=username&pass=password&smsfrom=1234&smsto=447700900999&split=2&
smsucs2=004c006f00720065006d00200069007000730075006d00200064006f006c006f0072002000730069007400200
061006d00650074002c00200063006f006e00730065006300740065007400750072002000610064006900700069007300
630069006e006700200065006c00690074002e002000410065006e00650061006e00200061007500630074006f0072002
00063006f006e00720020006c0069006200650072006f0020006100740020006f0072006e006100720065002e00200056
006900760061006d00750073002e HTTP/1.1
Host: sms.mxtelecom.com
HTTP/1.1 200 OK
Date: Wed, 05 Aug 2009 11:06:14 GMT
Server: Apache/1.3.26 (Unix) mod_ssl/2.8.8 OpenSSL/0.9.6a
Content-Type: text/plain
Transfer-Encoding: chunked
16
3408735312
3408735317
0
In the case of a forbidden operator (invalid username/password or attempting to send a reverse billing message where not allowed) the servlet will return an HTTP Forbidden error (code 403) and the body will contain an error message.
GET /SMSSend?user=username&pass=incorrectpassword&smsfrom=1234&smsto=447700900999
&smsmsg=Hello HTTP/1.1
Host: sms.mxtelecom.com
HTTP/1.1 403 Forbidden
Date: Tue, 25 Jun 2002 12:59:31 GMT
Server: Apache/1.3.26 (Unix) mod_ssl/2.8.8 OpenSSL/0.9.6a
Content-Type: text/plain
Transfer-Encoding: chunked
20
Forbidden
Bad username/password
0
In the case of a bad request - eg parameters missing/invalid the servlet will return a Bad request error (code 400).
GET /SMSSend?user=username&pass=incorrectpassword&smsfrom=1234
&smsto=447700900999 HTTP/1.1
Host: sms.mxtelecom.com
HTTP/1.1 400 Bad request
Date: Tue, 25 Jun 2002 12:59:31 GMT
Server: Apache/1.3.26 (Unix) mod_ssl/2.8.8 OpenSSL/0.9.6a
Content-Type: text/plain
Transfer-Encoding: chunked
21
Bad Request
Request type unknown
0
 |
About MX TelecomMX Telecom is a leader in wireless technology. MX Telecom offers an easily accessible gateway to data, voice and video messaging services including 2-way and premium SMS, multimedia messaging, interactive voice response, location-based services, video short codes, Internet and TV related solutions. For more information, MX Telecom can be reached on 1-877-MXTELECOM (+1 877 698 3532), or via email at sales@mxtelecom.com. |
