Messente logo

SMS Messaging API  

API Reference

SMS API allows you to do the following:

Send SMS API

Send SMS API allows you to send SMS to your clients. You can also provide a dlr-url callback URL where Messente makes Delivery Report request when the message has been delivered.

API endpoints

Primary API endpoint https://api2.messente.com/send_sms/
Backup API endpoint https://api3.messente.com/send_sms/

Request parameters

Key Value Required
username API account user name from the Messente's web page Yes
password API account security key (API key) from the Messente's web page Yes
text All characters (Unicode) and long messages are supported

* Either text field or data field must be provided
 No*
from Optional parameter that sets the Sender name. "from" value must be encoded in UTF-8.

* When not set, the default API Sender Name is used instead 		Yes*
to Receiver's phone number with the country code Yes
time_to_send Optional parameter for sending messages at some specific time in the future. Must be numeric Unix timestamp i.e. 1417190104.
If the time_to_send is set in past, message will be sent with no delays.
You can cancel sending this message with cancel_sms request. 		No 
dlr-url URL where the automatic Delivery Request is made. No
charset Encoding of "text" parameter value. Defaults to UTF-8 No
validity For how long the message is re-tried when the phone is switched off (in minutes). Defaults to 360 minutes (6 hours). No
autoconvert
Value Description
on (default) Use replacement settings from the account's API Auto Replace settings page
full All non GSM 03.38 characters will be replaced with suitable alternatives
off Message content is not modified in any way
No
udh SMS User Data Header in percent-encoded format No
data SMS message content in percent-encoded format

* Overwrites text field content if both data and text fields are provided. Either text field or data field must be provided
 No*
mclass Message class which determines to which component of the Mobile Station (MS) or User Equipment (UE) should be the message delivered
Value Description
0 Flash SMS
1 ME-specific
2 SIM/USIM specific
3 TE-specific
No
text-store Specify how the message content is stored in Messente:
plaintext (default) - message content is stored the same way the message was received by the handset
Value Description
sha256 message content is stored as sha256 hash
nostore message content is not stored in Messente
No

Successful request response codes

Code Meaning
OK [MessageID] Unique MessageID, which is specific to this message. This MessageID is used later to check for Delivery status

Error codes when the request failed

Code Meaning
ERROR 101 Access is restricted, wrong credentials. Check the username and password values.
ERROR 102 Parameters are wrong or missing. Check that all the required parameters are present.
ERROR 103 Invalid IP address. The IP address you made the request from, is not in the whitelist.
ERROR 111 Sender parameter "from" is invalid. You have not activated this sender name from Messente.com
FAILED 209 Server failure, try again after a few seconds or try the api3.messente.com backup server.

Note: In case Messente responded with HTTP 503 (Service unavailable) error code, make sure you are not exceeding 50 requests/second API request limit.

Delivery Report API

Delivery Report (DLR) is a response from the receipients handset, stating if and when it received the SMS.

When making a send_sms API request you can specify an optional dlr-url parameter. When this parameter is set, Messente makes a HTTP GET request to this URL when the DLR is received.

Tip: You can also provide the dlr-url in API settings page on the Messente API settings page. This URL will be used when the dlr-url parameter is not provided.

Request parameters

Key Value
sms_unique_id Text message ID that was returned with successful send_sms request
status This is a general delivery status, which shows if the message was delivered or not. Please refer to "stat" and "err" for more detailed information.

DELIVERED - SMS was successfully delivered. This is a final status.
FAILED - SMS could not be delivered. This is a final status.
SENT - SMS was sent but status about the delivery is not present yet
 stat Compared to "status" parameter, "stat" provides more detailed information about the delivery failure.

DELIVRD - SMS was successfully delivered
UNDELIV - Unable to deliver SMS to this number
FAILED - Failed to deliver SMS to this number
UNKNOWN - Unknown error occurred when delivering the message
ACCEPTD - Message was accepted for delivery
REJECTD - The delivery to this number has been rejected
DELETED - The message was deleted from the delivery queue
EXPIRED - The delivery of message expired
NACK - The message was not accepted for delivery
dlr-mask Numeric "status" values:
1 = DELIVERED
2,16 = FAILED
4,8 = SENT
err 000 - No error
001 - Failed to deliver SMS to this number
002 - Sending SMS expired in 6 hours
003 - Invalid number
004 - Error crediting Account
005 - Could not determine the destination country/operator or invalid number format
006 - Too many identical messages sent to the same number, blocked for 60 minutes
007 - Sender name not allowed
008 - Number is in blacklist
999 - General temporary error

Notes

The dlr-url parameter overrides the "DLR Response URL" value set in Messente's API settings.

Messente tries to make the Delivery Request 3 times. When the server defined in the dlr-url parameter is unable to respond for the SMS Delivery Request 5 times in a row, the SMS Delivery Request is dropped.

It may be possible that Messente makes multiple requests with different statuses. For example the first request with the status=SENT and after a minute, the same request with status=DELIVERED.

Synchronous Delivery Report API

If your server does not allow any incoming requests due to security reasons, you can also use the synchronous delivery report API to poll DLR from Messente.

API endpoints

Primary API endpoint https://api2.messente.com/get_dlr_response/
Backup API endpoint https://api3.messente.com/get_dlr_response/

Request parameters

Key Value Required
username API account user name from the Messente's web page Yes
password API account security key (API key) from the Messente's web page Yes
sms_unique_id ID that was returned with successful send_sms request Yes

Successful request response codes

Code Meaning
OK SENT Message has been submitted to the operator but does not yet have any Delivery Report yet
OK FAILED  Message delivery failed
OK DELIVERED  Message has been successfully received by the handset

Error codes when the request failed

Code Meaning
ERROR 101 Access is restricted, wrong credentials. Check the username and password values.
ERROR 102 Parameters are wrong or missing. Check that all the required parameters are present.
FAILED 102 No delivery report yet, try again in 5 seconds.
FAILED 209 Server failure, try again after a few seconds or try the api3.messente.com backup server.

Inbound Message API

The API endpoint where Messente makes the HTTP GET call can be configured under API Settings Inbound Numbers section.

Request parameters

Key Value
from Sender of this message (usually long number)
to Recipient number (your long number / shortcode) 
text Content of the message received
time Timestamp of the message delivery time - YYYY-MM-DD HH:MM:SS
msgid  Messente ID for this message

Cancel SMS API

Cancel SMS API is used when you scheduled a message with Send SMS API time_to_send but now need to cancel this message.

API endpoints

Primary API endpoint https://api2.messente.com/cancel_sms/
Backup API endpoint https://api3.messente.com/cancel_sms/

Request parameters

Key Value Required
username API account user name from the Messente's web page
  Yes
password API account security key (API key) from the Messente's web page   Yes
sms_unique_id MessageID to be cancelled  Yes

Successful request response codes

Response Description
OK DELETED Message with this MessageID has been successfully removed

Error codes when the request failed

Response Description
ERROR 101 Access is restricted, wrong credentials. Check the username and password values.
ERROR 102 Parameters are wrong or missing. Check that all the required parameters are present.
ERROR 107 Could not find message with this MessageID
FAILED 209 Server failure, try again after a few seconds or try the api3.messente.com backup server.