# SMS API

URL: https://developers.cuedesk.com/api/sms_api

> Send a single transactional SMS, such as a verification code, with the 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 [#basic-example]

```text
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 [#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 [#example-http-responses]

200

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

## Response Codes [#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 [#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? [#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? [#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? [#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: [#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:

```text
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
```
