ElementarySMS version 1.10
Welcome to ElementarySMS RestAPI Documentation
The ElementarySMS API is built on HTTP, is RESTful and it:
- Uses predictable, resource-oriented URLs.
- Uses built-in HTTP capabilities for passing parameters and authentication.
- Responds with standard HTTP response codes to indicate errors.
- Returns JSON.
Base URL
All API URLs referenced in this documentation start with the following base part:
http://elementarysms.example.com/api
You'll have to replace http://elementarysms.example.com
with the URL of your ElementarySMS Web Application installation.
Input and Output Formats
Unless otherwise specified, all API calls will require and return a JSON-formatted payload.
Authenticating API Requests
Authentication to ElementarySMS API occurs via Basic Access Authentication as described in RFC2617.
- The
user
name is alwaysapi-user
. - The
password
is theAPI Key
found in System Settings -> API Section of your ElementarySMS Web Application installation.
Here is how to use Basic Access Authentication with curl:
curl --user api-user:XXSSDDESSQQ
Sending Data to the APIs
By default, all API calls expect a JSON-formatted payload.
Here is a sample curl call for /message/add
:
curl --user api-user:XXSSDDESSQQ -H "Content-Type: application/json" -X POST \
-d '{
"number": "+40722001002",
"message": "This is a message sent through ElementarySMS API.\nHave a nice day :)"
}' \
http://elementarysms.example.com/api/message/add
Special note about handling new lines
If you want to use a new line in your message body, replace the new line with \n.
Receiving Data from the APIs
By default, all API calls will return a JSON-formatted payload.
Here is a sample response from /message/add
call:
{
"status": "success",
"uuid": "ea4b0fee-72ab-4d1f-9087-e8683ba355cf"
}
Date and Time Format
JSON does not have a built-in date type.
Dates
are passed or retrieved as Unix Time.
Here is a sample response from /message/status
call:
{
"status": "success",
"e6a0ed30-5c48-11e5-b604-2a042924705f": {
"device": "359385052343557",
"status": "delivered",
"added_at": 1442390388,
"queued_at": 1442390418,
"sent_at": 1442390419,
"delivered_at": 1442390437,
"sms_count": "1"
}
}
Using a specific Device
If you want to use a specific Device for an API call, you can pass a
device_id
parameter. You can find the Device ID inDevices
section of your ElementarySMS Web Application installation.
Here is a sample payload for /message/add
call using a specific device_id
:
{
"number": "+40722001002",
"message": "Hello John Doe, welcome to our site !",
"device_id": "LS1437838000"
}
Common HTTP Error Codes and Error Messages
HTTP status code 400
{
"status": "error",
"message": "Invalid JSON data !"
}
HTTP status code 401
{
"status": "error",
"message": "Invalid credentials !"
}
API References
Message
Messages
Get latest received messages.
Request body is required (not empty). Default, latest 25 messages received will be retrieved.