SMTP (Sophisticated) API for Sending & Receiving SMS

1. Overview

1.1. What is the SMTP API?

The HSL Mobile SMTP (Sophisticated) API allows seamless use of Internet email software (e.g. Microsoft Outlook, IBM Notes, Mozilla Thunderbird, Apple Mail) to hold two-way exchanges with any SMS compatible mobile device on a network reachable by HSL Mobile. No technical knowledge is required by either party in a message exchange and no user-level setup is required.

1.2. How does it work?

One side of the SMTP API receives email that you send to special email addresses and converts it into SMS messages that are delivered to mobile devices. The system also performs the reverse, converting SMS messages into emails that appear in your inbox. How does it do this? When you send a message through the system to a mobile device, your email address is associated with a special “virtual  mobile number”. It is this “virtual mobile number” that allows the bi-directional communication with mobile devices.

1.3. Dynamic and static virtual mobile numbers

A “virtual mobile number” is either automatically allocated to your email  address the first time you send a message to a mobile device, or is pre-allocated for you prior to use. This pre-allocation is performed by your account administrator specifying a static association between your email address and a “virtual mobile number”. This can be used to ensure that you are allocated a specific “virtual mobile number” and not simply the next available number.

2. Using the system

2.1. Which email addresses to use?

When sending to a mobile device via the SMTP API, each email address you send to has three parts that you must ensure are correct:

1. The first part must be an international version of the telephone number (MSISDN) that you wish to send to. This is constructed in much the same manner as when you dial an international voice call. For example, if you wanted to send a message to the UK number (07123) 4345678, it would become 447123456789 (drop the 0 and add 44 – the UK international code). It is important to note that only numeric characters should be included: characters such as “+” should be avoided.
2. The second component is the “@” that joins the international number onto the email domain.
3. The final part is the email domain name that your IS/IT administrator has provided you with for access to the SMTP API. This forms the part of the email address after the “@” character and completes it.

If we assume that the server name provided to you (constituting part 3 above) is “gms.yourcompany.com” then 447123456789@gms.yourcompany.com is the email address to use when sending to this mobile device through the GMI system.

2.2. Formatting your messages

You need take no special steps or precautions when composing emails destined for mobile devices, but there are certain semantics attached to the interpretation  of  your message and some general guidelines you should stick to.

2.2.1. Subject lines

If you type a subject line in your email it will be included as a distinct part of the SMS that is sent to the destination mobile device(s). There are,  however, two special  cases for subject lines: the first is that of an empty subject line, in which case the SMS will consist solely of the text you type in the main part of the email; the second is if any of the destination telephone numbers specified in the To: or Cc: fields is present in the subject line, in which case the SMS will again consist solely of the text from the main part of the email.

2.2.2. HTML/Rich text messages

In general, your email software will  provide  an  unformatted, plain text version of  your message if you send it as HTML or “rich text” – it is this unformatted text that the SMTP API processes. The reason for this is that mobile devices cannot (at least in terms of the vast majority of mobile devices) display such formatting.

Depending on which email client you use, it is possible that it may be configured to only send the rich text version of the message. If this is the case then the message body that you send will not reach mobile devices. If you think this may be the case, change your email client’s settings to have it send the plain text version as well. As a last recourse, it is possible to place the content of the message in the subject line and leave the body of the message blank; this will result in a message that is the same as if you left the subject line blank and specified only the main part of the email.

2.2.3. Message length

In general, messages sent via the SMTP API are limited to 160 Latin characters in length. Messages sent in languages that are not readable in Latin characters are processed differently and are restricted to at most 70 characters per SMS. This limitation is one imposed by the SMS standard. However, the SMTP API supports the splitting of email into multiple SMS per message by special   arrangement with HSL. Either way users should note that there is a relatively low limit on the length of message compared with sending regular email. As a consequence, users should always ensure that the message content they want to reach the mobile device is at the top of the email and is shorter than the limit agreed with HSL (e.g. a maximum of 5 SMS/800 characters). A good thing to do is to delete the quoted content from any reply you make when it is to be submitted to the SMTP API.

2.3. Storing addresses

The special email addresses used to send to mobile devices via the SMTP API can be stored in your email software’s address book. They can have all the same fields that normal addresses have, so long as the special email address itself is correct.  The special “reply-to” telephone number that appears (as the originator) on a mobile device when a response is being made to an Interface-originated SMS can also be stored in the mobile device’s address book. This allows a  mobile device to easily send an email to a specific person’s email address.

2.4. Specifying multiple recipients

You can send a  message  to any combination of normal email address and mobile devices (reachable via the SMTP API) and the recipients can be an arbitrary mix of To: and Cc: types. Please note that all mobile recipients will be restricted to the maximum message length as defined above.

2.5. Delivery receipts

You can request that a delivery receipt be returned when a message is actually delivered to the destination mobile phone. Such a request is made in the same way that you normally request a delivery receipt in your email client. For example, in Microsoft Outlook, you choose File | Properties from the menu on a new  email  message and then  click the “Delivery receipt requested” option (the setting is also available by clicking “Options…” in the toolbar on  a new message). The process is slightly different in Netscape Communicator; on a new message window click the “Options” button near the top and then make sure the “Return Receipt” option is selected/checked in the panel that appears.

2.6. Delay notifications

All messages sent through the SMTP API  are tracked and you will receive an email notification of any message you’ve sent that has become delayed or is undeliverable. These notifications of error conditions will be sent regardless of whether you originally requested a delivery receipt.

2.7. Supported languages

The SMTP API supports multiple language/character-set encodings (see Appendix A), though it is important to note that the receiving mobile device must also support any encoding used.

2.8. Holding multiple conversations

It is possible to hold conversations with multiple mobile devices via the interface at the same time by means of the SMTP API. This is because a unique special email address identifies each mobile device reachable via the SMTP API  – so it’s just like holding email conversations with multiple normal email addresses.

2.9. Message expiry (validity period)

Messages being sent to a mobile device will expire and never be delivered after a certain period  of time if delivery has  not already  taken place. The default time after which  an undelivered  message will expire is 20 minutes.  The default message expiry for your organisation’s account can be increased or decreased within the account’s configuration. An alternative method of specifying when you wish a particular message to expire is through the use of the “Expires after” option available in email software such as Microsoft Outlook (use View | Options menu when composing message to change).

3. Worked example

This section contains a worked example of the steps necessary to send a message to a mobile device via the SMTP API and to reply to that message from the mobile device. It builds upon the examples used in section 2.

3.1. Sending the email

The first step in the process is to fill out the details of the email that will be submitted to the SMTP API. This example uses the same destination address (in the To: field shown in the below figure) whose construction was covered in section 2.1 and contains a simple subject and message content.

 

Once all the details of the message are configured correctly, the message can be sent in the manner normal to your email software.

3.2. Receiving the SMS

The text of your message should quickly arrive on the intended destination mobile telephone/device.  Reading the SMS is achieved in exactly the same manner as with any other short message and simply choosing “reply” on your device will work as per normal.

3.3. Reading the mobile user’s reply

When the mobile user sends their reply, the message will travel back to your email software and appear in your inbox, just like any other email message. You can then open and read it, reply to it or delete it.

4. Caveats and limitations

4.1. The potential for delays

In certain rare instances it is possible for unavoidable delays to be encountered while using the system.  For example, email routing over the internet between your systems and the gateway can be subject to delay at any email server along the way or a mobile device may be out of coverage or have a full message memory.

4.2. Supported SMS types

The system is unable to transfer specialised forms of SMS data in the format intended: i.e. it is impossible to submit an image to the system and have it appear in readable form on the destination mobile device. Other examples of attempts that would fail are attempts to submit ringtones, operator logos etc. It is also important to note that attachments to messages will be ignored.

4.3. Beginning a conversation from a mobile device

To send a message from a mobile into the system,  you need to know the special virtual mobile number that has been assigned to them. You can either find this number out (i.e. from the person directly) and store it in your mobile telephone/device, or respond to any message previously sent to your mobile telephone/device by that person through the SMTP API.

4.4. Delivery receipts for MO messages

When a message is sent from a handset to the gateway, the handset will receive a “delivery receipt” from their mobile network when the  message reaches the gateway, as opposed to when the email arrives in the destination inbox. Unfortunately there is currently no way of altering this behaviour.

5. Security and Quotas

5.1. IP restrictions

The SMTP email server that you use to send messages to the SMTP API must have it’s public internet address (IP) associated with your account’s configuration so that  our systems will accept  messages from it. If your email server is not included within  your account’s configuration your messages will fail to be delivered to mobile devices and you will likely receive a delivery failure notice from your email server notifying you that it was unable to relay your message to the SMTP API.

5.2. Quotas

If quotas have been enabled on your account you will be limited to a maximum number of SMS messages in a  single 24 hour  period. The maximum number will  be the default maximum number specified for all users of your organisation’s account. Users who require a higher quota than the default maximum can have a specific quota set for them to allow them to send more messages.

If you use all of your quota you will have to wait up until 24 hours in order for your quota to be restored before the system will accept further messages from you. The system default is 5 SMS messages per 24 hours. Quotas only affect messages being sent to mobile devices and not message being sent to you from mobile devices.

6. Glossary

GMI	The Global Messaging Infrastructure,  An  architecture  comprising SMS messaging systems and technologies used to provide a two-way messaging service.
SMTP	The Simple Mail Transport Protocol. A long established internet standard for the communication of email messages, it is the de facto method for delivery of messages.
SMS	Short Message Service. A messaging service available to allow mobile users to send and receive messages containing textual and other content.
MO	Mobile Originated. A message created on a mobile device and transmitted from it into the wider communications network.
MT	Mobile Terminated. A message submitted to the gateway and forwarded to a mobile network for delivery to an SMS enabled device.

7. Appendix A – Supported character sets

7.1. Character sets that are converted to the GSM character set (Latin, 160 character message length)

Canonical Name	Description
ASCII	American Standard Code for Information Interchange
ISO-8859-1	ISO 8859-1, Latin Alphabet No. 1
ISO-8859-15	ISO 8859-15, Latin Alphabet No. 9
windows-1252	Windows Latin-1
windows-1250	Windows Central European

7.2. Character sets that are processed as Unicode (70 character message length)

Canonical Name	Description
UTF8	Eight-bit Unicode Transformation Format
UTF-16	Sixteen-bit Unicode Transformation Format, byte order specified by an optional initial byte-order mark
windows-1253	Windows Greek
windows-1254	Windows Turkish
windows-1255	Windows Hebrew
windows-1256	Windows Arabic
windows-1257	Windows Baltic
ISO-8859-2	ISO 8859, Latin Alphabet No. 2
ISO-8859-3	ISO 8859, Latin Alphabet No. 3
ISO-8859-4	ISO 8859, Latin Alphabet No. 4
ISO-8859-5	ISO 8859 Cyrillic Alphabet
ISO-8859-6	ISO 8859 Latin/Arabic Alphabet
ISO-8859-7	ISO 8859 Greek Alphabet
ISO-8859-8	ISO 8859 Latin/Hebrew Alphabet
ISO-8859-9	ISO 8859, Latin Alphabet No. 5
ISO-8859-13	ISO 8859, Latin Alphabet No. 7
EUC-JP	JISX 0201, 0208 and 0212 EUC; Japanese
x-EUC-JP-LINUX	JISX 0201 and 0208 EUC; Japanese (Linux)
Shift_JIS	Shift-JIS; Japanese
ISO-2022-JP	JIS X 0201, 0208 in ISO 2022 form; Japanese
x-mswin-936	Windows Simplified Chinese
GB18030	PRC Standard Simplified Chinese
x-EUC-CN	GB2312, EUC encoded Simplified Chinese
GBK	GBK Simplified Chinese
ISCII91	ISCII91 encoded Indic scripts
x-windows-949	Windows Korean
EUC-KR	KS C 5601, EUC encoded Korean
ISO-2022-KR	ISO 2022 encoded Korean
x-windows-950	Windows Traditional Chinese
x-MS950-HKSCS	Windows Traditional Chinese with Hong Kong extensions
x-EUC-TW	CNS11643 (Plane 1-3), EUC encoded Big5 Traditional Chinese
Big5	Big5 Traditional Chinese
Big5-HKSCS	Big5 Traditional Chinese with Hong Kong extensions
TIS-620	TIS620 Thai

Further characters sets are supported and added to the system as part of ongoing development and maintenance.