Call us
7 days
Australia
Bulk SMS Marketing - Reminders - SMS Integration
Australian owned & operated since 2014
REST API Documentation
Integrate SMS Sending & Receiving via our SMS REST API
Before you start...
To use this API, you will need an SMS Everyone account, a username, password and sender ID.
Please sign up for a free trial to get started.
Introduction
The REST API allows you to access SMS Everyone's full sending and receiving functionality.
This includes the sending of single messages and bulk campaigns
You can schedule, modify and delete campaigns.
Plus you can check the delivery status of messages, as well as your credit balance and account status.
If you have sub-accounts, you can programmatically top up their credits
You can even subscribe and unsubscribe end users.
We support the sending/scheduling in your time zone and we accept full unicode characters if required.
We highly recommend using SSL
Use of this API assumes a working knowledge of RESTful web APIs.
<<< Click on any of the links to the left to quickly jump to the required section.
Authentication
You will be provided with a username and password to access our API.
The username and password are sent in the authorization header. Type = Basic
eg: Authorization: Basic bWNo*****************bGUx
if you don't have a username and password, sign up and we'll give you 100 free credits to test with.
To create your basic authorization string, the format is USERNAME:PASSWORD then base 64 encode it.
for example, if your username was jimsbusiness and your password was s56sbdyte83fs the format would be:
jimsbusiness:s56sbdyte83fs
Then base 64 encode that string.
SMS REST formats and conventions
This section will take a brief look at some of the formats used in the REST API.
JSON
JSON (application/json) is the content type of both requests and responses if not otherwise specified.
eg: Content-Type: application/json
Requests with invalid JSON will be rejected.
New features might result in additional request and response parameters. New request parameters will either have a default value or
considered optional to retain backwards compatibility. It is highly recommended to ignore any unexpected parameters when reading JSON in API responses.
Header Examples
cURL
--header 'Authorization: Basic bWNo*****************bGUx' \
--header 'Content-Type: application/json' \
C#
request.AddHeader("Authorization", "Basic bWNo*****************bGUx");
request.AddHeader("Content-Type", "application/json");
Phone numbers (MSISDN)
Only MSISDNs in international format without the + sign are accepted by the API.
For example to send to the Australian number 0400123456, the format would be 61400123456.
For the New Zealand number 021123456, it would be 6421123456
All MSISDNs returned by the REST API will be without a + or 00 prefix, even if they were sent in with one.
Timestamps
Timestamps are used for expressing a moment in time. They are represented using the ISO-8601 standard without the time zone extension.
An example of this is the received field for SMS replies to show when a reply SMS was received by the system. eg: 2020-07-27T10:01:10
All timestamps returned by the API can be represented in your local time or UTC. Just let us know what you prefer.
HTTP Status Codes
The REST API returns an HTTP status and code each time a request is made.
The following HTTP status codes are used by the API. Additional codes might be added in the future and if you encounter a code not in this list please contact us for a definition.
HTTP Errors
Where we pass back an error, there will be a JSON object in the body explaining the error. It has the following structure:
Error Codes
If there is an error with your request, the following error codes can be returned as values for the code field:
Sending SMS Messages
Be sure to read the Authentication section above before you send.
The following operation will send an SMS message or a bulk SMS campaign.
Individual characters used in the message determine the type of encoding that will ultimately be used to send the SMS message. The API automatically detects the encoding required from the characters used, which allows us to support the delivery of SMS in any language.
Depending on the length of the message field, one message might be split into multiple parts and charged accordingly.
The limit of a single SMS is 160 characters including spaces, carriage returns, line feeds etc.
Once you exceed 160 characters, the SMS is broken into chunks of 153 characters.
(7 characters are required to tell the phone that it is part 1 of 3, part 2 of 3, part 3 of 3 etc.
Character limits per SMS message:
1 SMS = 160 characters
2 SMS = 306 characters (2 x 153)
3 SMS = 459 characters (3 x 153)
4 SMS = 612 characters (4 x 153)
5 SMS = 765 characters (5 x 153)
Unicode
As soon as you include a unicode character in the message field, the character limit drops to 70 characters. Once you exceed 70 characters, the SMS is broken into chunks of 67 characters.
Character limits per unicode message:
1 SMS = 70 characters
2 SMS = 134 characters (2 x 67)
3 SMS = 201 characters (3 x 67)
4 SMS = 268 characters (4 x 67)
5 SMS = 335 characters (5 x 67)
Basic Character Set
You can send up to 160 characters in a single SMS message if all characters in your message are part of the GSM 7-bit character set:
LF is the Line Feed character - for JSON format, provide it as \n
SP is the Space character
Extended Character Set
The following characters are also available, but they are counted as two characters in the SMS message rather than one:
| , ^ , € , { , } , [ , ] , ~ , \
Other Characters
If other characters are required for different languages, 16-bit Unicode (UCS-2) encoding will be used. When using UCS-2 encoding, each character will take 2 bytes, which means up to 70 characters can be sent per UCS-2 encoded SMS message.
Long Messages
The message body in a request can contain up to 2000 characters. Longer messages will be split and sent as multiple distinct SMS messages. In most cases, those messages will be re-assembled on the handset and displayed to the end-user as a single long message.
Request
The URL to POST to is https://smseveryone.com/api/campaign
JSON Body fields:
Send a message to one recipient
{
"Message": "Hello, this is a test",
"Originator": "61400190499",
"Destinations": [
"61400123456"
],
"Action": "create"
}
Send a message to two recipients
{
"Message": "Hello, this is a test",
"Originator": "61400190499",
"Destinations": [
"61400123456",
"61400123999"
],
"Action": "create"
}
Schedule a message to five recipients with a reference ID
{
"Message": "Hello, this is a test",
"Originator": "61400190499",
"Reference": "1234567",
"TimeScheduled": "202008301300",
"Destinations": [
"61400123456",
"61400123999",
"61400123888",
"61400123777",
"61400123666"
],
"Action": "create"
}
Add 5 more numbers to the existing scheduled bulk campaign above
{
"Message": "Hello, this is a test",
"Originator": "61400190499",
"Reference": "1234567",
"TimeScheduled": "202008301300",
"Destinations": [
"61400123000",
"61400123111",
"61400123222",
"61400123333",
"61400123444"
],
"Action": "create"
}
Send an SMS to a stored list (You must upload a list to our web interface or via the API and have the CRMID first)
{
"Message": "Hello, this is a test to a list",
"Originator": "61400190499",
"TimeScheduled": "202307141230",
"Reference": "123456",
"Action": "create",
"CrmIds": [4398]
}
Responses for successfully created campaigns
The JSON response object contains the following parameters:
JSON RESPONSE EXAMPLES
Response when sending to one recipient
{
"Code": 0,
"CampaignId": 11967222,
"Messages": 1,
"Segments": 1,
"Credits": 1
}
Response when sending to two recipients
{
"Code": 0,
"CampaignId": 11967222,
"Messages": 2,
"Segments": 1,
"Credits": 2
}
Response when sending to five recipients and you've supplied a reference ID and a schedule time
{
"Code": 0,
"CampaignId": 11967222,
"Messages": 5,
"Segments": 1,
"Credits": 5
}
Response when adding 5 more numbers to the above scheduled message
{
"Code": 0,
"CampaignId": 11967222,
"Messages": 5,
"Segments": 1,
"Credits": 5
}
Error Response when the destination number is missing or incorrect
{
"Message": "No valid destination number(s) specified",
"Code": -111
}
Error Response when the message text field is blank
{
"Message": "Campaign message text not specified",
"Code": -117
}
Error Response when there are not enough credits on the account
{
"Message": "Insufficient credits available to start campaign",
"Code": -202
}
Cancel a scheduled SMS message
To cancel/delete a campaign, submit our campaignID and the delete action to the same URL as above.
{
"CampaignId": 11967218,
"Action": "delete"
}
Response
200 OK
The JSON response object for a successfully cancelled message is:
{
"Message": "Deleted",
"Code": 0
}
Modify a scheduled SMS message
To modify the message text, originator or send date/time of a campaign, submit our campaignID and the modify action to the same URL as above. Note: the destinations field is not required to modify a campaign.
{
"Message": "Modified message text",
"Originator": "61400111222",
"CampaignID": "111626243",
"TimeScheduled": "202008301330",
"Action": "modify"
}
Response
200 OK
The JSON response object for a successfully modified message is:
{
"Code": 0,
"CampaignId": 11967222,
"Messages": 5,
"Segments": 1,
"Credits": 5
}
Pause a scheduled message
To pause a campaign, submit our campaignID and the pause action to the same URL as above. You cannot pause a campaign that is scheduled in the past.
You can attempt to pause a campaign that is sending now, however our gateway sends at very high speeds and it is unlikely you will pause the campaign before it finishes unless the campaign is very large.
{
"CampaignId": 11967218,
"Action": "pause"
}
Response
200 OK
The JSON response object for a successfully paused message is:
{
"Message": "Paused",
"Code": 0
}
Unpause a scheduled message
To unpause a campaign, submit our campaignID and the unpause action. Unpausing a campaign that was scheduled to be sent in the past will send it immediately.
{
"CampaignId": 11967218,
"Action": "unpause"
}
Response
200 OK
The JSON response object for a successfully paused message is:
{
"Message": "Unpaused",
"Code": 0
}
Check the status of a campaign
To check the status of a campaign, submit our campaignID and the status action.
{
"CampaignId": 11967218,
"Action": "status"
}
Response
200 OK
The JSON response object contains the following parameters:
JSON examples
Paused campaign:
{
"Message": "Paused",
"Code": 0
}
Scheduled campaign:
{
"Message": "Scheduled",
"Code": 0
}
Running campaign:
{
"Message": "Running",
"Code": 0
}
Deleted campaign:
{
"Message": "Deleted",
"Code": 0
}
Check the delivery status of a campaign or message
(Delivery receipts)
You can check the delivery status of either a single message or retrieve the delivery status of all messages in a bulk SMS campaign.
If you are sending single messages at a time, you can submit just the campaign ID as there will only be one destination per campaign.
If you are sending in bulk (more than one mobile number per post) you have the option to request just the status of one of the mobile numbers in that bulk campaign or all of the numbers in that campaign (that we have delivery status info for)
To retrieve the status of all numbers in the campaign, submit only the CampaignID
To retrieve just the info on one of the numbers, submit the CampaignID and the specific Destination
Note: SMS carriers can try for up to 24 hours to reach a mobile handset if they are having trouble delivering. If we have not received a delivery receipt from the handset, we will not return any delivery status results in the JSON response. You can try again later if required.
Request
POST to the URL https://smseveryone.com/api/DRStatus
JSON Body fields:
JSON examples
Checking for delivery status of all mobile numbers on campaign ID 11967215. This can be just one mobile number or many.
{
"CampaignId": 11967215
}
Checking for delivery status of just the mobile number 61400123456 on campaign ID 11967215
{
"CampaignId": 11967215,
"Destination": "61400123456"
}
Response
200 OK
The JSON response object contains the following parameters:
JSON response examples
Successful delivery of an SMS to 61400123456
{
"CampaignId": 11967215,
"Count": 1,
"Destinations": [
{
"Destination": "61400123456",
"TimeStamp": "2020-07-28T11:06:02",
"Status": {
"DeliveryReceiptStatusId": 1,
"Code": 0
}
}
]
}
Failed delivery to 61400123456. This is a permanent error (the mobile number can be deleted) The reason is 'Invalid destination'
(See Delivery Status Error Codes below)
{
"CampaignId": 11967218,
"Count": 1,
"Destinations": [
{
"Destination": "61400123456",
"TimeStamp": "2020-07-28T11:29:16",
"Status": {
"DeliveryReceiptStatusId": 2,
"Code": 300
}
}
]
}
No delivery status information available yet for campaign ID 11967210 OR you have submitted a campaignID that doesnt belong to your account.
{
"CampaignId": 11967210,
"Count": 0,
"Destinations": []
}
Delivery Status codes
The following table contains the possible delivery status codes and their explanation
Delivery Status Error Codes
The following table contains a description of the error codes that we pass to you in the code field when a message fails.
These codes come directly from the carriers and we pass them through to you without altering them.
This info may not include all of the possible carrier codes as there are many and they are subject to change. New codes may be added over time.
Permanent errors are when there is no point trying to send again as the number is dead, not provisioned, cancelled etc.
You can remove these numbers from your database.
Temporary errors are when the phone is unreachable, out of credit, the network is down etc.
You can try again at another time and you may be successful.
Retrieving SMS Replies via REST
You can send a POST to our replies API to retrieve all SMS replies on your account.
Use the same Basic authentication that you use to send an sms campaign.
Request
POST to the URL https://smseveryone.com/api/replies
If you don't add any extra fields in the body, (however still put the curly brace {} brackets in the body) we will pass back all replies for your account since the last time you checked. Any replies we pass to you are then flagged our end as 'retrieved' so that we don't pass them to you again unless you specify a date range and/or use one of the JSON body fields below.
The recommended frequency for checking for any new replies is every 5 minutes.
The minimum time allowed is every 1 minute. Please do not check this API any more often than 1 minute.
JSON Body fields:
JSON examples:
To retrieve all replies on your account since you last checked:
{
}
To test replies without us flagging them as retrieved
{
"Test": true
}
To check replies for the last 2 days. (Note: we show results from 12am your time until now for the number of days selected)
{
"Days": 2
}
To check replies for a date range.
{
"DateStart": "2020-06-01",
"DateEnd": "2020-06-30"
}
Response
200 OK
The JSON response object contains the following parameters:
JSON examples
Retrieving 2 replies:
{
"Count": 2,
"Messages": [
{
"Received": "2020-07-27T10:01:10",
"Originator": "61400123456",
"Recipient": "61400190444",
"MessageText": "Thanks, yes i will be at the appointment",
"ReferenceId": "4499850"
},
{
"Received": "2020-07-27T11:35:10",
"Originator": "61400987654",
"Recipient": "61400190555",
"MessageText": "Can we reschedule?",
"ReferenceId": "4499851"
}
]
}
No messages available to retrieve:
{
"Count": 0,
"Messages": []
}
SMS Replies via Webhook (HTTP GET to your URL)
If you are using us via a single connection (not multiple accounts or sub-accounts), we can post SMS replies to a URL of yours via HTTP GET (JSON unavailable at this time)
Contact Us to discuss options or to set this up.
The following table includes all of the fields we pass to you.
You must respond with nothing but a 0 (zero) so that we know you received the data. No HTML. Just plain text.
Example HTTP GET String Sent from SMS Everyone to Your Site:
http://yourwebsite.aspx?username=xyz&password=xyz&originator=61402756334&recipient=61429848254&reference=4255525&message_text=Hello
Retrieve Remaining Credits, User ID & Send status
You can send a POST to our 'Retrieve User Settings' API to get your SMS Everyone UserID, your current balance and whether your account has unicode enabled and the ability to send messages longer than a single message. Additional information may be added to this API call at any time.
Request
POST to https://smseveryone.com/api/RetrieveUserSettings
You only need basic authorization. No Body fields required.
Response
200 OK
The JSON response object contains the following parameters:
JSON examples
A balance of 116 SMS credits remaining on the account, the account can send unicode sms, messaging is limited to Australia only and userID is 9999:
{
"UserId": 9999,
"AllowUnicode": true,
"AllowInternational": false,
"Credits": 116,
"Code": 0
}
A balance of 119 SMS credits remaining on the account, the account can not send unicode sms, messaging is worldwide and userID is 9998:
{
"UserId": 9998,
"AllowUnicode": false,
"AllowInternational": true,
"Credits": 119,
"Code": 0
}
Optouts
SMS Everyone maintains an Optout Database for every client.
All SMS messages are washed against your optout database at the time of sending.
Contact Us if youd like to use one of our opt out numbers in your messages. This way if anybody replies to the optout number, they are automatically added to your optout database and you cannot send them a message again.
This REST API allows you to manually add mobile numbers to your optout database, opt a number back in (resubscribe) and retrieve a list of all optouts on your account.
Request
POST to https://smseveryone.com/api/optouts
JSON Body fields:
JSON examples:
To opt out (unsubscribe) the numbers 61400123456 and 61400222333
{
"Action": "add",
"Originator": [
"61400123456",
"61400222333"
]
}
To opt the number 61400123456 back in. (resubscribe)
{
"Action": "delete",
"Originator": [
"61400123456"
]
}
To retrieve a list of all opted out numbers
{
"Action":"list"
}
Response
200 OK
The JSON response object contains the following parameters:
JSON examples
Successfully opted out a number:
{
"Message": "Origins added",
"Code": 0
}
Successfully opted a number back in:
{
"Message": "Deleted 1 OptOut number",
"Code": 0
}
Retrieving a list of all optouts. (2 opted out numbers are associated with the account):
{
"Count": 2,
"OptOut": [
{
"Added": "2018-12-05 18:52:42",
"Originator": "61400555555",
"MessageText": "",
"Reason": "Client"
},
{
"Added": "2016-12-02 15:11:40",
"Originator": "61400999999",
"MessageText": "",
"Reason": "Client"
}
]
}
Lists
SMS Everyone allows you to store lists of mobile phone numbers in our database if required.
This way you can send SMS campaigns to pre-stored lists of any size (see Sending an SMS) instead of passing us all of the mobile phone numbers for each campaign every time you send.
You can also retrieve the list data via our web interface or via an API call
We allow you to add and delete lists as well as add and delete numbers within those lists.
One usage example might be that you have a website with a sign up form or somewhere that an end user can add their mobile number to receive updates or alerts. When they enter their mobile number, you hit our API with the 'Append' Action and add the mobile number to a list to be sent to later. If they unsubscribe, unsubscribe them via our Optouts API.
Request
POST to https://smseveryone.com/api/crm
JSON Body fields:
JSON examples:
LIST - To retrieve a list of all of your CRM Groups (lists) in our database:
{
"Action": "list"
}
DETAILS - To retrieve all of the mobile numbers in the list with list ID 1234
{
"Action": "details",
"CrmId": 1234
}
CREATE - To create a list called 'Daily VIP client SMS' with 2 numbers in it.
{
"Action": "create",
"Description": "Daily VIP client SMS",
"Records": [
{
"Number": "61400123456,61400999111"
}
]
}
APPEND - To add 2 more numbers to the above list. (You will have retrieved the CrmID from our JSON response when you created the list)
{
"Action": "append",
"CrmId": 14456,
"Records": [
{
"Number": "61400111555,61400222333"
}
]
}
REMOVE - To remove a number from the above list.
{
"Action": "remove",
"CrmId": 14456,
"Records": [
{
"Number": "61400111555"
}
]
}
DELETE - To delete the above list.
{
"Action": "delete",
"CrmId": 14456,
}
Response
200 OK
The JSON response object contains the following parameters:
JSON examples
LIST - Retrieving a list of all lists in your database. (4 lists retrieved)
{
"Count": 4,
"Groups": [
{
"CrmId": 123,
"Description": "Saturday Night SMS",
"Count": 76,
"ParentGroup": 0,
"ActiveCampaign": 0,
"Deleted": ""
},
{
"CrmId": 710,
"Description": "Staff List",
"Count": 6,
"ParentGroup": 0,
"ActiveCampaign": 0,
"Deleted": ""
},
{
"CrmId": 2494,
"Description": "The Boss",
"Count": 1,
"ParentGroup": 0,
"ActiveCampaign": 0,
"Deleted": ""
},
{
"CrmId": 756,
"Description": "VIP list",
"Count": 494,
"ParentGroup": 0,
"ActiveCampaign": 0,
"Deleted": ""
}
]
}
DETAILS - Retrieving all of the numbers in a list. (6 mobile numbers in the list)
{
"CrmId": 710,
"Description": "Staff List",
"Count": 6,
"Records": [
{
"Number": "61400000000"
},
{
"Number": "61400999888"
},
{
"Number": "61423090878"
},
{
"Number": "61423646978"
},
{
"Number": "61434222777"
},
{
"Number": "61444888777"
}
]
}
CREATE - List successfully created.
{
"CrmId": 2496,
"Message": "CRM created"
}
APPEND - Successfully added 1 number to an existing list.
{
"Message": "Added 1 number",
"Code": 0
}
REMOVE - Successfully removed 1 number from an existing list.
{
"Message": "Removed 1 number",
"Code": 0
}
DELETE- Successfully deleted a list.
{
"Message": "Deleted",
"Code": 0
}
Add credits
You can add credits to an account via our credits API call. The usage scenario is more for software partners who have many sub-clients. Your software can hit our API requesting that the sub-account be topped up by x number of credits, we bill you at the end of the month for all top ups and you bill your clients accordingly. Ideally your software should send you an alert whenever a sub client tops up.
Please note: This is only for pre-approved clients and will return an error if you attempt to add credits via this method without approval.
Request
POST to https://smseveryone.com/api/credits
Authentication
Use basic auth as per all other API calls above. However the username and password must be of the sub-client that the credits are to be added to, not any parent/master account.
JSON Body fields:
JSON examples:
To add 1000 credits to an account:
{
"credits" : 1000,
"action" : "add"
}
Response
200 OK
The JSON response object contains the following parameters:
JSON examples:
Successfully added 1000 credits to an account and the new balance is 8488 credits:
{
"Credits": 8488,
"Code": 0
}
Attempting to add credits to an account that does not have approval from SMS Everyone.
{
"Message": "Not allowed to add credits",
"Code": -129
}
Attempting to add a negative amount of credits to an account or adding 0 credits.
{
"Message": "Invalid amount of credits to add",
"Code": -130
}
Extras
Time zones
We can set your account to any time zone in the world so that when you specify the send time, it will be in that countries’ time zone. Contact SMS Everyone to set this up.
Send Window
To prevent your staff or clients sending sms messages at inconvenient times, we can enable a send window on your account. This prevents sending sms outside of whatever hours you specify. For example, you could set your account to only send between 8am and 9pm in your time zone.
If you schedule/send before the window opens, we queue it until the window opens.
If you schedule/send after the window closes, we queue it for the following day when the window opens.
Contact SMS Everyone to set this up.
International SMS
We can send SMS to pretty much any country in the world. Contact us to discuss your requirements as there are certain restrictions in some countries and some countries require sender numbers (origins) to be set up and approved by the carriers.
Unicode Characters / International languages
We can send and receive SMS messages in any language. This includes emojis. eg 🎈🏀😀👽
See the unicode section under 'Sending SMS Messages' above as different character limits apply.
Contact Us for more information