Local Mail Docs
Search…
Quickstart
Messaging
Whatsapp
Email
Verification
Lookup Services
SMS Parameters overview
Below is a more detailed description of the parameters in the SMS request body (JSON object submitted to the API)
source
The source value can also be called senderID or TPOA.
It is the from address that will be used when delivering the SMS to the handset.
It can take different formats:
Alphanumeric (example: MyBrand): this is the case when a source is composed of an alphanumeric string (max 11 characters: letters from the ASCII character set, digits and the space character). Alphanumeric sources are generally used for branded SMS to help the SMS receiver to identify the brand or services which originated the SMS.
Numeric (example: +6512345678): this the case when a source is composed of a string made purely of digits (max 17 chars). It can also start with the + sign. Numeric sources are generally used when the originator intends to receive an answer to the SMS as it is interpreted as a regular phone number by the destination handset.
Limitations: According to the country where the SMS is sent to, source can be overwritten in order to ensure a better delivery. If you have some specific inquiries related to the type of source available for your account towards a specific destination, please contact your account manager.
Destination
This is the destination phone number for the SMS.
The destination should be submitted following the international format and should include the country code (the leading + sign can be omitted but this is not an obligation).
(Valid examples include: +6512345678, 6512345678)
We also accept national formats (for national you have to specify the country in the dedicated field).
Reference
This value is not mandatory.
If used, the reference allows you to submit SMS associated with your custom message ID. That way, you are able to match the information contained in the API response with the ID from your own business logic. You can later read reference from delivery reports.
The maximum length allowed for the reference is 80 characters.
Text
The text or the message (or SMS body) is the main part of your SMS: it is what is going to be displayed on the destination handset.
It can contain characters from the GSM7 character set or from the UNICODE character set.
According to the encoding of the SMS, the number of SMS accounted per message will be proportional to the length of the text:
For GMS7 messages:
if the total length of the message is inferior or equal to 160 characters then the first and only message part can accommodate 160 characters.
If the total length is greater than 160 characters then each message part can contain 153 characters (less characters can be fit into one part as extra data space is taken to concatenate the SMS on the destination handset)
For Unicode messages:
if the total length of the message is inferior or equal to 70 characters then the first and only message part can accommodate 70 characters.
If the total length is superior to 70 characters then each message part can contain 67 characters (less characters can be fit into one part as extra data space is taken to concatenate the SMS on the destination handset)
For Unicode messages, 70 characters = 1 SMS (1 part)
The maximum length for a message is 10 message parts. Longer messages will be truncated to this limit and sent.
Encoding
AUTO: the API will analyze the content of your SMS text and select the correct encoding according to the characters used: if your SMS text contains UNICODE characters, then UNICODE will be selected, otherwise it will be GSM7
GSM7: by using GSM7, you are forcing the encoding in use to be GSM 7 bit: it will render correctly any of the characters from the character set (See a complete list).
Localmail API considers each block of 160 GSM 7 bit characters as 1 SMS unit.
UCS2: by using UCS2, you are forcing the encoding in use to be UNICODE: it will render correctly any of the characters from the UNICODE character set (See a complete list).
Local Mail API considers each block of 70 UNICODE characters as 1 SMS unit.
Scheduled
The scheduled parameter should be used if you wish to schedule your message up to 7 days in advance. The SMS will be stored on the Localmail platform and sent out at the predefined time and date. You can specify the scheduling timestamp using the standard ISO 8601 format (which includes and specifies the timezone offset to use): "scheduled":"2016-11-07T19:20:30+08:00"
Reporturl
The reporturl allows to specify a webhook URL (a.k.a callback url) that will be used to POST the delivery reports for the SMS sent in the request
If included in the request, the webhook URL in the request will be used instead of your default account webhook.
We strongly recommend to set a default webhook (a.k.a callback url) for your account (by sending a request to ) and use the reporturl field only when you want to overwrite the default webhook.
Example: "reporturl":"https://your-webdomain.com/localmail/sms-webhook"
Last modified 1yr ago