Sending messages via HTTP/HTTPS
At sms2email.com, we're committed to providing trouble-free service. If you're connecting to our gateway, we recommend that you read our
backup gateway document. At sms2email, we run 4
gateways on 2 different networks. The backup gateway document gives examples of how to design your systems to connect to a different gateway
in the rare instance that one of our gateways does not respond.
Here is an example php script an example asp script and an example shell script for connecting to our gateway* (shell script kindly written by Ethan Galstadt of Nagios for sms2email.com. Thanks Ethan!). There is
also a pear module under development. This includes basic functions such as message sending and also advanced functions such as address book definitions. Please see the CVS for full information.
*note - the bash script is also a notification script which can be used by Nagios users. For more information, please see here.
An example using curl is given below, which can be incorporated
as the posting agent within a php or perl script.
On the BASH/CSH/KSH/ZSH command line (linux/sunos) with
CURL installed type...
curl -d to_num=447778123456 -d message=hello+world http://username:email@example.com/sms/postmsg.php
Or, using LYNX which is also standard with most installs of
RedHat lynx -dump -auth=username:password
If you'd like us to put together a quotation/specification for an sms or database driven project, please
The syntax for the request is as follows...(note: this gateway supports both POST and GET)
Via standard port 80
[all on one line]
[all on one line]
Via SSL port 443
[all on one line]
[all on one line]
username = username of your sms2email account
password = password of your sms2email account
to_num = mobile number of recipient - entered in international format (eg 07778123456 would be entered as 447778123456
- omit the leading zero and add the country code for the uk which is 44)
message = message string (separate each word by a "+" sign to indicate a space)
flash = this field is optional, set flash=1 to send the message as a flash text message. This means that the message
will be displayed on the recipients phone without the phone announcing the message or storing it.
orig = this field is optional. Set orig=newname to set your originator to a specific originator name for that message. Omitting this
field will mean that your default originator is used.
Server Response Codes
Multiple Message Gateway
When an sms request is posted to our gateway, it will issue one of the following responses,
which you can log or echo to your client or trigger an event.
AQSMS-NOAUTHDETAILS = The username and password were not supplied
AQSMS-AUTHERROR = The username and password supplied were incorrect
AQSMS-NOCREDIT = The account specified did not have sufficient credit
AQSMS-OK = The message was queued on our system successfully
AQSMS-NOMSG = No message or no destination number were supplied
AQSMS-CREDIT = <number of messages> The output if the string cmd=credit is added to
the query - allowing users to track their account balance via our http interface : eg.
This means that you can use the sms2email textback service and log the clients data
via your own server and database rather than the data being stored on our system.
We can also offer support and consultancy on this subject. In addition we can
accept your SIM cards for incorporation into our modem banks. This will allow
us to accept text messages on your own private number without the need for a keyword. Contact
us for prices.
Our multiple message gateway allows a single message to be sent to multiple mobiles in a single HTTP request. The Syntax for the request is identical to the above except in the following regards:
Delivery Notification via HTTP Gateway
Definition modification :
to_num = comma seperated list of mobile numbers. Please make sure the whole list conains no spaces
note - the URL is : http://gw1.sms2email.com/sms/postmsg-multiple.php (or https://gw1.sms2email.com/sms/postmsg-multiple.php)
Server Response Code modifications:
AQSMS-OK:x = From the list above, x messages were queued on our system successfully. This response code will be received in place of AQSMS-OK
If any of the numbers are invalid, this gateway will still send messages to the valid numbers. The 'x' reflects the number of VALID mobile numbers that messages were queued for. It is recommended that all mobile numbers be validated before they are sent to the gateway.
When sending messages via our systems, it is possible to track the delivery status of each message. This
can be accomplished by appending an extra variable to the postmsg.php request:
Along with setting the username, password, destination number, message (and
optionally the originator), the variable "dlrurl" can be specified
which includes an URL Encoded address of a script on your server, with 2 optional
parameters included. An example of this use is shown below:
Sending a message with the following details:
message=this is my message
dlrurl = http://test.sms2email.com/deliveryreport.php?reportcode=%code&destinationnumber=%dest&myreference=123
The dlrurl has 2 special values in it - %code and %dest - these are substituted
for the real report code and destination number. Any other variables can be
set by you for your own tracking of the message submitted, for example myreference
in this case.
%dest = destination number of message
%code = delivery report code
The %code values are:
1 = Delivered to Handset
2 = Rejected from Handset
4 = Buffered in transit (phone probably off / out of reception)
8 = Accepted by SMSC
16 = Rejected by SMSC
All of the details of the message have to be encoded for sending via a HTTP
GET request, so put together - the final request looks like:
http://gw1.sms2email.com/sms/postmsg.php? username=test&password=test&to_num=447740123456&orig=sms2email& message=this+is+my+message&dlrurl=http%3A%2F%2Ftest.sms2email.com%2Fdeliveryreport.php%3Freportcode%3D%25code%26destinationnumber%3D%25dest%26myreference%3D123
Once the message gets processed, our system would simply call the address set
by dlrurl, substituting %code for the delivery code value and the same for the
%dest value. So, if the message were successfully delivered to the handset,
your system would receive the following request: