SMTP (Simple) API for Sending SMS

1. Description

The HSL Mobile SMTP API allows the use of Internet standards based email infrastructure to send Short Message Service (SMS) messages to mobiles via HSL’s messaging servers. Messages in both text and binary formats can be sent to mobiles as mobile terminated (MT) SMS.

2. Relevant Standards

RFC2821 Simple Mail Transfer Protocol
RFC2822 Standard for the Format of ARPA Internet Text Messages
RFC1894 An Extensible Format for Delivery Status Notifications
RFC1123 Requirements for Internet Hosts – Application and Support
GSM 03.38 Digital cellular telecommunications system (Phase 2+); Alphabets and language-specific information
SMPP v3.3/3.4 Short Message Peer to Peer (SMPP) Interface Specification

3. Usage Modes

3.1 Normal Mode (basic)

The destination mobile number is included in the SMTP envelope recipient value. For example,

The message content to be included in the MT (mobile terminated) SMS is normally contained in the subject line and/or body of the RFC822 message. Where content is included in both the subject line and body, the SMS message will comprise of the subject line content enclosed in brackets, ‘(‘ and ‘)’, with the body content following. Where content is only contained in either the subject line or the body the SMS
message will solely comprise of that content.

Subject line and body content encoding using base-64 are supported. Plain text MIME attachments are also supported.

For example, the following results in the message “(This is my message in the subject) This is my message” being sent to mobile number +447973100000:

SMTP Envelope


SMTP Data / RFC822 Component (Headers and body)


3.2 SMPP SubmitSM Encapsulation Mode

The fields of the MT SMS can be specified using fields in the RFC822 headers of the mail message. The content of the SMS is contained only in the headers of the email can contain 8-bit data encoded as ASCII hexadecimal. The body of the email is ignored and should be empty. The destination mobile number can be specified using email headers and a single destination email address can be used (e.g. Where the SMTP envelope recipient address contains the mobile number the x-smpp-destination-addr field should not be used.

The fields of the MT SMS are contained in X-headers in the RFC822 message. The following X-header fields are defined:

x-smpp-destination-addr (international MSISDN)
x-smpp-short-message (ASCII hexadecimal encoding)
x-smpp-esm-class (numeric, decimal, default: 0)
x-smpp-protocol-id (numeric, decimal, default: 0)
x-smpp-data-coding (numeric, decimal, default: 0)
x-smpp-validity-period (absolute or relative timestamp)

The above fields correspond with destination_addr, esm_class, protocol ID and data_coding fields that are present in the SMPP submit_sm PDU (see SMPP v3.3 specification). The data_coding field values are defined in GSM 03.38. The esm_class field value should be set to 0 by default or 64 (decimal) when a UDH is present in the SMS. The protocol ID value should generally be set to 0 or  63 (decimal).

Note that where the data coding used is 8-bit the maximum length of the short message is normally 140 octets. Otherwise the maximum length of the short message is normally 160 characters (7-bit).

For example, the following results in an operator logo being sent to mobile number +447973100000:

SMTP Envelope


SMTP Data / RFC822 Component (Headers with empty body)


4. Sending a Message to Multiple Mobiles

When using the SMTP envelope to specify the destination of a message, it is possible to send to multiple mobiles by including multiple “RCPT TO” email address entries when communicating with HSL’s SMTP receivers.

Email clients conforming to RFC2821, such as Microsoft Outlook, send emails in this way when the sender includes multiple email address entries in the “To” field of an email.

5. Delivery Confirmations

A delivery confirmation can be received for the outcome of a message sent to a mobile number. The confirmation is sent by email to the email address from which the message was sent.
A delivery confirmation can be requested by the inclusion of a delivery receipt/confirmation request. Such requests are made using the following headers in the email:


For example, a message sent to a mobile from will result in a delivery confirmation being returned from HSL’s systems by email to when one of the above headers is included. The delivery confirmation will be sent when the message reaches completion (i.e. is delivered or can not be delivered at all).

Deliver status notifications are in accordance with RFC1894.

6. Long Messages – Concatenated SMS

Due to the limitation that a single SMS message can contain only 160 7-bit characters or 70 UCS2/Unicode characters, it is necessary for a longer message to be conveyed using more than one SMS. One way of accomplishing this is by simply splitting the message in multiple SMS that will be received by a mobile and presented to the user as separate messages.

An alternative that is often more preferable to the mobile user is for a single long message to be received rather than multiple separate parts. Through the use of  “concatenated SMS” a single long message can be presented to the mobile user as a result of multiple SMS sent to the user’s mobile. This is made possible through the inclusion of segmentation and reassembly (SAR) information contained within each part of the message being sent to the user’s mobile.

The method used for sending a long message via SMS is based on the configuration of your account on HSL’s systems. The configuration selects if SAR information for long messages is automatically included in the SMS sent to mobile users by HSL’s systems.

The default setting is to use concatenated SMS for long messages. To change this setting on your account please contact HSL Support.

7. Subject Lines

Individual accounts can be configured to ignore the body of the email and only use the subject line. This can prove useful when you wish to omit an automatically added disclaimer from messages sent to mobile telephones. The default is to use both the subject line and body for messages being sent to mobiles. To change this setting on your account please contact HSL Support.

8. Two-Way Messaging

This API does not support two-way messaging. Please see the separate 

9. Closed User Groups

A closed user group can be used to restrict the mobile numbers to which users of an account can sent messages. By default closed user groups are not enabled. To change this setting on your account please contact HSL Support.

10. Quota Management

Individual users can be assigned a quota to limit the number of SMS messages that they are permitted to send in a 24-hour period. Additionally, an account can have an account-wide default quota for users that would be used where individual users have not been given a specific quota. By default quotas are not enabled. To change this setting on your account please contact HSL Support.

11. Appended Text

An account can be configured to have every message sent through that account have a pre-defined text appended to the message contained in the email. Uses of this include standard disclaimers, company names and advertising. By default no text is appended to messages. To change this setting on your account please contact HSL Support.

12. Security

When communicating with HSL’s servers the SMTP transmitter IP address, SMTP envelope originator and recipient values are compared with the allowed values on an account. This allows the SMTP receiver to authenticate the incoming communication. An incoming communication that does not pass authentication will not be permitted to progress with their communication.

Where available for your service, a VPN connection between your SMTP servers and HSL’s SMTP servers can be setup to secure communication over the Internet.

Note that SMS is typically not encrypted between the base station and the mobile handset.

13. Character Translation

The RFC822 component communicated in the SMTP session must contain ASCII or ISO-8859-1 content and may be encoded in base-64 where necessary.

UCS2 content may be conveyed using SMPP SubmitSM Encapsulation Mode as described in this document.

Messages sent to mobiles are translated into either the GSM alphabet or UCS2 for transmission over mobile networks.

The GSM alphabet is contained in Appendix A.

14. Appendix A – GSM Alphabet (7-bit)

See GSM alphabet