Australia
Call us
7 days
Bulk SMS Marketing - SMS Reminders - SMS Integration
Australian owned & operated since 2014
​
SMS HTTP API
Send SMS via HTTP POST or GET
Before you start...
You'll need an SMS Everyone account, username and password. So please sign up for a FREE TRIAL first.
Please Note: Our REST API has slightly more functionality than our HTTP one so if you want the full package, we recommend
that you use REST
​
Introduction
This document outlines the interfaces by which SMS messages can be sent and received over standard HTTP (web) protocol. We support both HTTP POST and GET.
​
We strongly recommend that you send via HTTPS. If you send via HTTP, we may force an HTTPS connection.
​
Please note: MMS Messages cannot be delivered via this HTTP interface.
Sending SMS (MT)
The SMS Everyone web service allows you to send messages from your website/software to any mobile phone.
This is known as a Mobile Terminated (MT) message.
​
MT messages are sent by sending an HTTP request (POST or GET) directly to the SMS Everyone web service address:
HTTPS (Recommended)
https://api.smseveryone.com/ws/campaign
​
HTTP
http://api.smseveryone.com/ws/campaign
​
HTTP Parameters to send SMS messages
The basic HTTP parameters are the same for sending & receiving messages.
The following table outlines the parameters that you will need to include in your http request.
Note that we accept all variations of the parameters listed in the parameters field below.
​
Eg ‘USER_NAME’, ‘user’, ‘username’, ‘usr’ & ‘name’ are all accepted as the ‘user name’ field name.
​
Thus, we provide compatibility with most other major SMS provider API’s so in many cases, you'll simply need to change the base URL and you are up and running.
​
If your field names are hard coded, let us know if you need any other field names than the ones below.
​
Scheduling Campaigns
This service allows you to schedule SMS’s to be sent at a later date/time by passing the date and time you would like the message sent as a parameter in your POST.
You can modify scheduled campaigns provided that you supply us with a reference ID for the campaign.
See 'Parameters for modifying a campaign' below.
​
You can also delete scheduled campaigns up to 1 minute prior to the message being sent provided you supply us with a reference ID.
See the ‘Parameters for Deleting a Campaign’ section below.
Parameters for Scheduling a Campaign for a later date/time
Modifying, deleting & pausing a campaign
You can modify a scheduled campaign up to 1 minute before a campaign is due to send.
You can also delete a scheduled campaign and pause a campaign.
Parameters for deleting a campaign
Parameters for pausing a campaign
Parameters for checking status of a Campaign
Send Status of Message
After submitting the HTTP request to the SMS Everyone Gateway, you should expect to receive an HTTP response.
The response code you receive will indicate whether the SMS message was successfully passed to our gateway.
A response with the number zero (0) indicates that you have successfully submitted your message to SMS Everyone, while any other response indicates that the message failed to be submitted as well as the reason for that failure. Eg you don't have enough credits or a field is missing etc
Successful HTTP Response Sample
​
0
A failed response has the error code or the error code and a description of the error condition.
Failure HTTP Response Sample
​
-300 Incorrect User or Password
There are a number of failure codes that can be returned, depending on the reason for the message failure. See HTTP Error Codes below for a list of valid expected response codes and descriptions.
​
Additional HTTP response options for a successful post
​
We can respond with custom HTTP responses to match your existing code and additional fields to give you extra information about your post.
For example, if you need something like ‘OK’ instead of 0 for a successful post, contact us and we can change it our end in a few seconds.
​
Additional fields are:
​
Credits Used
We can respond with the number of credits that were used by your post to help you with billing your end.
For example, you could be sending a double message to 3 mobiles, so we can respond with 0 for success plus the number of credits used, separated by a comma.
0,6
​
Reference ID
We can send you back the SMS Everyone reference ID of the message. Eg:
0,1234567
​
Message Character Counts & Unicode Messages
​
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.
(It will appear as a single message on the phone though)
​
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 below:
LF is the Line Feed character
SP is the Space character
CR is carriage return
​
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.
Receiving SMS (MO)
You can also receive messages from any mobile phone. This is known as a Mobile Originated (MO) message. There are 2 options for receiving replies:
​
OPTION 1 - Receiving real time to your web service via webhook
MO messages are forwarded to your nominated website address (URL) by SMS Everyone via an HTTP GET request.
This is mainly used where you have a single URL that we can post all replies to.
A correctly configured page on your web site must be set up to receive messages of this type and you must return the correct HTTP response of 0 (zero). Nothing else.
The fields we pass to you are:
-
username (if required)
-
password (if required)
-
message_text
-
originator (the end user’s mobile number)
-
recipient (our virtual mobile number)
-
reference (a unique reference ID)
See the samples section later in this document for an example string.
​
OPTION 2 - Receiving messages on demand (2 WAY)
MO messages are stored on our URL by SMS Everyone.
Your system ‘polls’ our web service (via HTTP POST or GET) and retrieves replies in batches as required.
We will only pass replies to you that have not yet been retrieved.
This system is used where you have multiple instances of your software (eg if you have sold your software to multiple clients) and you need to get replies to the right account and/or you don’t have a specific URL we can point to.
For example: appointment reminder software on multiple client’s computers. This requires the outbound message to have been sent via our MT API so that we can route the reply to the correct account.
​
Please do not hit our replies API any more frequently than once a minute.
Recommended frequency is once every 5 minutes.
To retrieve reply (MO) messages from our web service, send either an HTTP POST or GET to:
HTTPS (Recommended)
https://api.smseveryone.com/ws/replies
​
HTTP
Retrieving All Unretrieved Replies
Retrieving All Replies for a given period
The HTTP response will show all replies for your selected period regardless of whether they have been retrieved previously or not.
HTTP Response - CSV
Plain text is returned. We only show the replies that we have received since you last checked. Ie whenever you poll for replies, we mark those reply messages as retrieved in our database so that we don’t show them to you again.
The HTTP response CSV format is:
​
ResponseCode,#OfMessages,Mobile1,Message1,DateTime1,Mobile2,Message2,DateTime2,etc...
Example:
0,2,0402756333,Yes,2014-11-12 01:32,0439897906,Yes,2014-11-12 01:32
​
If there are no messages to be retrieved:
0,0
Notes:
-
ResponseCode will always be 0 (zero) unless there is an error.
-
#OfMessages = the number of replies we are passing to you in this HTTP response
-
DateTime is in the following format: YYYY-MM-DD HH:mm (24 hour format)
-
Mobile is in 04 format for all Australian mobiles and International format for all international mobiles
-
Standard CSV formatting applies – For example:
-
Commas within the text will result in speech marks either side of the text so you know this particular comma is not a delimiter. Eg:
Yes, I’ll be there will appear as "Yes, I’ll be there" -
Speech marks will result in double speech marks. Eg:
I’m going to be "late" today will appear as "I’m going to be ""late"" today"
-
HTTP Response – JSON
-
If there are no messages, the response will be:
{
"Count": 0,
"Messages": []
}
-
Count = the number of replies we are passing to you in this response
-
‘Received’ date time is in this format: YYYY-MM-DD HH:mm:ss (24 hour format)
-
All mobile numbers are in international format without the + sign
-
We include a reference ID for each reply message
-
Example:
{
"Count": 1,
"Messages": [
{
"Received": "2020-06-04 16:39:14",
"Originator": "61402756333",
"MessageText": "🦄",
"ReferenceId": "4436768"
}
]
}
HTTP Response – XML
-
If there are no messages, response will be
​​
<Replies>
<Count>0</Count>
<Messages />
</Replies>
​
-
Count = the number of replies we are passing to you in this response
-
‘Received’ date time is in this format: YYYY-MM-DD HH:mm:ss (24 hour format)
-
All mobile numbers are in international format without the + sign
-
We include a reference ID for each reply message
-
Example:
​
<Replies>
<Count>1</Count>
<Messages>
<Reply>
<Received>2020-06-04 16:40:34</Received>
<Originator>61402756333</Originator>
<MessageText>, ",</MessageText>
<ReferenceId>4436771</ReferenceId>
</Reply>
</Messages>
</Replies>
Checking SMS Credit Balance
To check your balance of SMS credits, send an HTTP POST or GET to
HTTPS (Recommended)
https://api.smseveryone.com/ws/creditcheck
​
HTTP
http://api.smseveryone.com/ws/creditcheck
​
The HTTP response is plain text showing only of the number of credits.
Example:
203
A zero balance will show
0
Add SMS Credits
You can add credits to an account via our add 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.
SOME EXAMPLES:
​
1. MANUAL TOP UP BY SUB-CLIENT – In your software have a credits top-up section that allows your client to select the number of credits that they want to top up by (eg: 1000, 2000, 5000 & 10,0000) or type in the number of credits manually.
Your software then hits our API which tops them up immediately and we respond with the new balance so you know that it worked. Then make sure that your software sends you an alert of some kind so that you can bill your client. We then bill you at the end of the month for all top ups in the previous month.
​
2. AUTOMATIC TOP UP – Your software detects whenever the account is getting low by hitting the above creditcheck API before every send. When the balance is below a certain threshold, hit our add credits API and top them up automatically.
​
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.
​
Below are the API calls pertaining to adding credits:
HTTPS (Recommended)
https://api.smseveryone.com/ws/credits
​
HTTP
The HTTP response is plain text showing the standard "0" response plus the new balance of the account.
For example, this is a successful top up with the new balance being 1023 credits:
0,1023
Trying to add a negative number of credits error:
​
-130,Invalid amount of credits to add
​
Trying to add credits to an account that does not have approval:
​
-129,Not allowed to add credits
​
Optouts/Unsubscribes
SMS everyone maintains an optout database for every client. We wash every single sms sent against your optout database. Anybody who is opted out cannot be sent an SMS.
​
If you are using our API to send marketing messages, you will need to provide either your own optout functionality your end or you can use our optout system. Either way you will probably need an optout number so that your end recipients can reply to opt out. Contact us for an optout number if required.
​
Below are the API calls pertaining to opt outs:
​
HTTPS (Recommended)
https://api.smseveryone.com/ws/optouts
​
HTTP
http://api.smseveryone.com/ws/optouts
Add a number to our optout database (opt out / unsubscribe)
Delete a number from our optout database (opt back in / re-subscribe)
By deleting a number from our optout database, you acknowledge that the recipient has opted back in.
Retrieve a list of all numbers that are opted out / unsubscribed
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.
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.
Sample HTTP Strings
Sending a message immediately
​
Scheduling a message to be sent later
​
Modifying a scheduled campaign - changing originator
​
​
Modifying a scheduled campaign - changing send time
​
​
Modifying a scheduled campaign - changing message text
​
​
Deleting a scheduled Campaign
​
Checking the status of a scheduled Campaign
​
​
Checking for all un-retrieved replies
​
https://api.smseveryone.com/ws/replies?username=UserName&password=Password
Checking for all replies in the last 7 days
​
https://api.smseveryone.com/ws/replies?username=UserName&password=Password&days=7
Checking for all replies from April 1st 2020 – April 3rd 2020 from the number 61402111222
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%20There
Unsubscribing a number (optout)
​
https://api.smseveryone.com/ws/optouts?user=Username&password=Password&action=add&origin=61400222333
Resubscribing a number (opt back in)
Retrieve a list of all opt outs
https://api.smseveryone.com/ws/optouts?user=Username&password=Password&action=list
The plain text CSV HTTP response will be in the following format:
​
Mobile number 1,Date opted out,Message text (if available),How they opted out (originator = the end user opted out, Client = the client manually opted them out),Mobile number 2,etc
For example
61400555555,05-12-2018 07:52,Stop please,Originator,61400999999,02-12-2016 04:11,,Client
JSON format:
​
{
"Count": 4,
"OptOut": [
{
"Added": "2020-06-09 11:44:24",
"Originator": "61400000000",
"MessageText": "STOP",
"Reason": "Originator"
},
{
"Added": "2020-06-09 11:44:24",
"Originator": "61400000001",
"MessageText": "",
"Reason": "Client"
},
{
"Added": "2020-06-09 11:42:03",
"Originator": "61400999777",
"MessageText": "",
"Reason": "Client"
},
{
"Added": "2018-12-05 18:52:42",
"Originator": "61400555555",
"MessageText": "",
"Reason": "Client"
}
]
}
XML format:
​
<OptOuts>
<Count>4</Count>
<OptOut>
<OptOut>
<Added>2020-06-09 11:44:24</Added>
<Originator>61400000000</Originator>
<MessageText/>STOP<MessageText/>
<Reason>Originator</Reason>
</OptOut>
<OptOut>
<Added>2020-06-09 11:44:24</Added>
<Originator>61400000001</Originator>
<MessageText/>
<Reason>Client</Reason>
</OptOut>
<OptOut>
<Added>2020-06-09 11:42:03</Added>
<Originator>61400999777</Originator>
<MessageText/>
<Reason>Client</Reason>
</OptOut>
<OptOut>
<Added>2018-12-05 18:52:42</Added>
<Originator>61400555555</Originator>
<MessageText/>
<Reason>Client</Reason>
</OptOut>
</OptOut>
</OptOuts>
Http Response Codes
Error Code | Error Description |
---|---|
-2 | Account suspended. Please contact SMS Everyone for more info. |
-132 | Invalid date range |
-131 | Campaign originator invalid. You must send from a registered origin |
0 | Message is OK (so far). Or successful response. |
-100 | Campaign create attempt with no CampaignID or ClientRef specified |
-101 | Campaign create attempted to modify a deleted campaign |
-102 | Campaign create attempted to modify a running campaign |
-103 | Campaign create attempted to modify a completed campaign |
-104 | Deletion request after campaign start time cutoff |
-105 | Campaign deletion request for campaign that does not exist |
-106 | Deletion request for completed campaign |
-107 | Deletion request for previously deleted campaign |
-108 | Campaign rescheduled due to outage |
-109 | Campaign rescheduled due to unknown reason |
-110 | Campaign start time has already past |
-111 | Campaign no destination number(s) specified |
-112 | Campaign not specified for delete action |
-113 | Campaign originator length invalid |
-114 | Campaign originator contains invalid characters |
-115 | Campaign schedule date invalid |
-116 | Campaign message length too long. Specify concat option for longer messages |
-117 | Campaign message text not specified |
-118 | Campaign ID not specified for status action |
-119 | Campaign Unicode characters not allowed in Message Text |
-120 | Attempt to modify a non-existent campaign. Check Campaign Id |
-121 | Attempt to remove numbers from invalid campaign |
-122 | Invalid action specified |
-123 | Attempt to retrieve status of non-existent campaign. Check Campaign Id |
-124 | Modification request after campaign start time cutoff |
-125 | No valid Destinations or ListIds found to schedule |
-127 | CampaignId not found |
-128 | CrmId not found |
-129 | Not allowed to add credits |
-130 | Invalid amount of credits to add |
-200 | Credits remaining enquiry failed to locate Credit record |
-201 | Credits to use for campaign not specified |
-202 | Insufficient credits available to start campaign |
-203 | Insufficient credits available to complete campaign |
-204 | Insufficient business grade credits available to start campaign |
-205 | Insufficient business grade credits available to complete campaign |
-206 | Credit account is inactive |
-207 | Credit record already exists for client |
-500 | Default gateway offline. Using failover gateways. Contact SMS Everyone ASAP |
-501 | Default gateway offline. Using system default gateway. Contact SMS Everyone ASAP |
-502 | Default gateway offline. Campaign processing halted. Contact SMS Everyone ASAP |
-503 | Default gateway offline. No failover gateways found. Contact SMS Everyone ASAP |
-504 | Gateway offline. End-point unavailable. Contact SMS Everyone ASAP |
-505 | Gateway offline. Manually set. Contact SMS Everyone ASAP |
-506 | Gateway Offline. Unknown Reason. Contact SMS Everyone ASAP |
URL Encoding
Why do we need URL Encoding?
The specification for URLs poses a problem, in that it limits the use of allowed characters in URLs to only a limited subset of the US-ASCII character set. This means that messages using characters not contained within that character set must be represented by alternative methods.
​
How are characters URL Encoded?
URL encoding of a character consists of a "%" symbol, followed by the two-digit hexadecimal representation (case-insensitive) of the ISO-Latin code point for the character.
Example
​
Space = decimal code point 32 in the ISO-Latin set.
32 decimal = 20 in hexadecimal
The URL encoded representation will therefore be %20
Line feed = %0A
What characters need to be encoded and why?
Reserved Characters
WHY: These characters have a special role or syntax within URL’s and should not be used as part of a parameter value. These characters must always be encoded.
WHICH CHARACTERS:
​
Un-Safe Characters
WHY: Some characters present the possibility of being misunderstood within URLs for various reasons. These characters should also always be encoded
WHICH CHARACTERS:​