SMS API

Use this endpoint for sending a single transactional SMS. Examples of this could be sending a verification code to a user via SMS or another similar type of notification.

Basic Example

GET https://cuetechnologies.sms-console.com/json?action=message_send&username=userx&password=passwordy&to=27820123456&from=12345&text=URL+encoded+text+string&client_reference=REF123456

Parameters

Parameter	Value example	Required	Description
action	message_send	Required	Set to message_send for this endpoint
username	<your_username>	Required	Your account username
password	<your_password>	Required	Your account password
to	27821230000	Required	Recipientʼs phone number
from	27821230000	Required	Sender ID – this can be any value and can be used as an internal reference
text	Your OTP is: 12345	Required	URL Encoded message text content
client_reference	REF123456	Optional	Your own reference code that will be returned in status updates.
charset		Optional	Defaults to GSM 7 bit (Advanced)
auto_detect_encoding		Optional	Default to “yes”, this ensures that is special characters are used the system will encode the message correctly. This may incur extra costs.
report_mask		Optional	Defaults to 19, only used with report_url
report_url		Optional	If provided, our system will call this URL with a delivery status update for the message

Example HTTP Responses

200

{
  "status": 1,
  "message": "Sent",
  "details": "8beda1a8–5c12–489f-0107–123000000003"
}

Response Codes

The API will return a JSON object with a status and message field. The status field indicates the overall success or failure of the request.

Status Code	Message	Description
1	Sent	The message was successfully sent.
2	Queued	The message has been queued for sending.
-1	System Error	An unexpected error occurred on the server.
-2	Authentication Failed	The username or password provided is incorrect.
-3	No Credit	Your account has insufficient credit to send the message.
-4	Invalid Destination	The recipient's phone number is invalid.
-5	Invalid Sender ID	The 'from' parameter is invalid or not allowed for your account.
-6	Invalid Parameter	A required parameter is missing or an invalid value was provided for a parameter.
-7	Duplicate Client Reference	The client_reference provided has already been used.
-8	Message Too Long	The message text exceeds the maximum allowed length.
-9	Blacklisted Destination	The recipient's phone number is on a blacklist.
-10	Account Suspended	Your account has been suspended.
-11	Feature Not Enabled	The requested feature is not enabled for your account.
-12	Missing Required Parameter	A parameter marked as 'Required' was not provided.
-13	Invalid Action	The 'action' parameter is invalid.
-14	Invalid Character Set	The 'charset' parameter is invalid.
-15	Invalid Report Mask	The 'report_mask' parameter is invalid.
-16	Invalid Report URL	The 'report_url' parameter is invalid.

Delivery Reports via API

When sending a message with Cue, you can also provide a URL to receive a callback with the delivery status update of this message. If using HTTPS, you need to add two additional fields to your request:

• report_url: The HTTP URL for us to request when the status changes
• report_mask: Which status messages you would like to receive

What is a report mask?

The report mask is what is known as a bitmask field indicating which status messages you want to receive.

What are the different delivery status codes?

Status Code	Description
1	Delivered
2	Undelivered
4	Queued at network
8	Sent to network
16	Failed at network

How to calculate the report mask?

To calculate the report mask, you need to pick the status codes you want to receive, and then add them together! And that’s your report mask.

For example, I want to know whether my message was delivered or failed. (1, 2, and 16)

report_mask = 1 + 2 + 16 = 19

So, in your next request, send report_mask=19 and we’ll send you these status messages where applicable.

Give me an example:

Ok, so we want to send a message and receive status reports to our server when the message is delivered or fails.

Our request parameters will look like this:

Parameter	Example Value
username	myusername
password	mypassword
to	27821340000
from	271112221113
text	Hello there, we are testing delivery reports!
report_mask	19
report_url	http://myserver.com/receive_report.php?myMessageId=12345&status=%d

The resulting URL (once we encode the data) for the request will look like this:

https://cuetechnologies.sms-console.com/json?action=message_send&username=myusername&password=mypassword&to=27821340000&from=271112221113&text=Hello+there%2C+we+are+testing+delivery+reports%21&report_mask=19&report_url=http%3A%2F%2Fmyserver.com%2Freceive_report.php%3FmyMessageId%3D12345%26status%3D%25d