Login
API - SMS
The SMS API facilitates sending messages, and accessing resources such as SMS Inboxes and Messages (planned).
In order to access this API method, please ensure you have correctly set permissions for the relevant API Key. See Creating a new API Key
Base URI
Base URI: https://myapi.maxo.com.au/
Sending Messages
Endpoint: sms/send
Permissions Required
SMS/Send Messages
Example
The API example below is called via standard HTTP GET request, however all parameters can be posted or included in a JSON array.
https://myapi.maxo.com.au/sms/send/?key=[key]&origin=[sender id]&destination=[to number]&message=[uri-encoded message]
or to send from a particular SMS Inbox, use the smsInbox parameter as the resource in the URI as follows:
https://myapi.maxo.com.au/sms/[smsinbox]/send/?key=[key]&origin=[sender id]&destination=[to number]&message=[uri-encoded message]
Supported Parameters
Attribute | Supported Values | Required | Notes |
key | The API key from My Account Portal | Yes | |
origin | Virtual Mobile Number | Yes | Additional Sender ID's can be validated in the My Account portal |
destination | AU Mobile Number | Yes | A valid 10 digit AU mobile number beginning with 04 |
| message | URI-Encoded Text | Yes | Check the GSM standard for information on maximum length, and unicode characters. Unicode characters are supported, however they will reduce the allowable maximum length of the message. Multiple message parts will result in an increased cost of the final message. |
smsinbox | The SMS Inbox ID | No | Sending from an SMS Inbox is a good way to keep your messages organised, and allows you to more easily retrieve and delete them later. To get a list of SMS Inboxes on your account, see sms/list. SMS Inboxes allow easier grouping of messages for different business units and help keep messages separate in the My Account portal. |
API Responses
Successful Response
A successful request to the API will result in a HTTP 200 response, with a json object containing status:1
The ID of the message is returned (smsid), as well as the number of message parts and the price charged.
{
"status":1,
"request":"sms\/send",
"smsid":1980554,
"parts":1,
"price":0.1
}
Successful Response - Result
For JSON The following parameters are returned
Field | Description |
| smsid | Unique ID of the message |
| parts | Total number of message parts sent and charged |
| price | Price in Dollars |
Unsuccessful Response
An unsuccessful request to the API will result in a HTTP response other than a 200 OK, and json with status:0.
Examples of unsuccessful HTTP codes include 401 Unauthorised, 404 Invalid method, a 400 Bad Request/Incomplete request, or 403 Forbidden if the supplied key has insufficient permissions for the method or resource.
An example of a validation error where the destination number was not valid.
{
"status":0,
"request":"sms\/send",
"error":"VALIDATION",
"reason":"Sending to International numbers is not supported"
}
List Inboxes
Endpoint: sms/list
Permissions Required
SMS/Get SMS Inbox
Example
The API example below is called via standard HTTP GET request, however all parameters can be posted or included in a JSON array.
https://myapi.maxo.com.au/sms/list?key=[key]
Supported Parameters
| Attribute | Supported Values | Required |
|---|---|---|
| key | The API key from My Account Portal | Yes |
API Responses
Successful Response
A successful request to the API will result in a HTTP 200 response, with a json object containing status:1
The count of inboxes is returned (smsid), as well as the smsinbox ids, description and sender id.
{
"status": 1,
"request": "sms/list",
"count": 2,
"smsinboxes": [
{
"smsinbox": 10,
"name": "Customer SMS",
"senderid": "0480011223"
},
{
"smsinbox": 11,
"name": "Staff SMS",
"senderid": "0483322110"
}
]
}
System and default inboxes are not available through the API.
Successful Response - Result
For JSON The following parameters are returned
Field | Description |
| count | Total number of SMS inboxes |
| smsinbox | ID of the SMS inbox |
| name | Description of the SMS inbox |
| senderid | Name or number shown on outbound messages |
Unsuccessful Response
An unsuccessful request to the API will result in a HTTP response other than a 200 OK, and json with status:0.
Examples of unsuccessful HTTP codes include 401 Unauthorised, 404 Invalid method, a 400 Bad Request/Incomplete request, or 403 Forbidden if the supplied key has insufficient permissions for the method or resource.
Retrieving Messages
Endpoint: sms/<smsinbox>/messages
Permissions Required
SMS/Get SMS Inbox
Example
The API example below is called via standard HTTP GET request, however all parameters can be posted or included in a JSON array.
https://myapi.maxo.com.au/sms/[smsinbox]/messages?key=[key]&startTime=[date]&endTime=[date]&outputFormat=csv&showHeadings=1
Supported Parameters
Attribute | Supported Values | Required | Notes |
| smsinbox | The SMS Inbox ID from sms/list | Yes | |
key | The API key from My Account Portal | Yes | |
startTime | Date Unix timestamp | Yes | Start date to list messages from. Eg. 2024-06-01 |
endTime | Date Unix timestamp | Yes | End date to list messages up to. Eg. 2024-06-30 |
| contact | Mobile number | No | Show results only for the contact's mobile number |
| outputFormat | csv | No | Return results as a downloadable csv file |
| showHeadings | 1 0 | No | When outputFormat = csv, include field headings in the output file |
API Responses
Successful Response
A successful request to the API will result in a HTTP 200 response, with a json object containing status:1
The ID of the message is returned (smsid), as well as the number of message parts and the price charged.
{
"status": 1,
"request": "sms/10/messages",
"timezone": "Australia/Brisbane",
"offset": "+10:00",
"starttime": "2023-06-01 00:00:00",
"endtime": "2024-05-20 00:00:00",
"count": 2,
"messages": [
{
"smsid": 2864649,
"smsinbox": 10,
"datetime": "2023-08-22 10:56:49",
"unixtime": 1692665809,
"contact": "0499887766",
"direction": "Receive",
"origin": "0499887766",
"destination": "0480011223",
"status": "Delivered",
"read": 1,
"cost": "0",
"message": "Test message 10.56.50"
},
{
...
}
]
}
Successful Response - Result
For JSON The following parameters are returned
Field | Description |
| smsid | Unique ID of the SMS message |
| smsinbox | ID of the SMS inbox |
| datetime | Friendly date and time the message was sent/received |
| contact | Mobile number of the 3rd part sender/receipient |
| direction | Direction of the SMS, either Receive (inbound) or Send (outbound) |
| origin | The mobile number of the sender |
| destination | The mobile number of the recipient |
| status | Delivery status of the message |
| read | Whether the message has been opened |
| cost | The price in dollars of the message |
| message | The content of the message |
Unsuccessful Response
An unsuccessful request to the API will result in a HTTP response other than a 200 OK, and json with status:0.
Examples of unsuccessful HTTP codes include 401 Unauthorised, 404 Invalid method, a 400 Bad Request/Incomplete request, or 403 Forbidden if the supplied key has insufficient permissions for the method or resource.
Further Information
As further functionality becomes available, full permissions, functions, and API descriptions will be available in our upcoming developer portal.
For further assistance with any API CDR related queries, please reach out to MaxoTel support.
Date created: Nov 9, 2022
Last modified: Sep 12, 2024
Would you like to speak to our 
Australian Sales team about our phone system plans?
Australian Sales team about our phone system plans?