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.

HTTP parameters to send sms. sms http api

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.

modify an sms campaign via api. sms http api

Parameters for deleting a campaign

Parameters for pausing a campaign

Parameters for checking status of a Campaign

check status of sms campaign. sms http api

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

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

http://api.smseveryone.com/ws/replies

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,0402123456,Yes,2014-11-12 01:32,0439123456,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": "61402123456",

"MessageText": "🦄",

"ReferenceId": "4436768"

}

]

}

HTTP Response – XML

If there are no messages, response will be

</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:

<Reply>

</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

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

http://api.smseveryone.com/ws/credits

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

retrieve a list of unsubscribes. sms http api

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

https://api.smseveryone.com/ws/campaign?user=UserName&password=Password&originator=JIMSBAR&destination=61412333444&message=Hello_There!

Scheduling a message to be sent later

https://api.smseveryone.com/ws/campaign?username=UserName&password=Password&originator=JIMSBAR&destination=61412333444&message=Hello_There!&time=201501010900&campaignid=123

Modifying a scheduled campaign - changing originator

https://api.smseveryone.com/ws/campaign?username=UserName&password=Password&campaignid=123&action=modify&originator=changed

Modifying a scheduled campaign - changing send time

https://api.smseveryone.com/ws/campaign?username=UserName&password=Password&campaignid=123&action=modify&send_time=202003061530

Modifying a scheduled campaign - changing message text

https://api.smseveryone.com/ws/campaign?username=UserName&password=Password&campaignid=123&action=modify&message_text=changed

Deleting a scheduled Campaign

https://api.smseveryone.com/ws/campaign?username=UserName&password=Password&campaignid=123&action=delete

Checking the status of a scheduled Campaign

https://api.smseveryone.com/ws/campaign?username=UserName&password=Password&campaignid=123&action=status

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

https://api.smseveryone.com/ws/replies?username=UserName&password=Password&startdate=202004010000&enddate=202004032400&origin=61402111222

HTTP GET String Sent from SMS Everyone to Your Site

http://yourwebsite.aspx?username=xyz&password=xyz&originator=61402123456&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)

https://api.smseveryone.com/ws/optouts?user=Username&password=Password&action=delete&origin=61400222333

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:

<Reason>Originator</Reason>

</OptOut>

<Reason>Client</Reason>

</OptOut>

<Reason>Client</Reason>

</OptOut>

<Reason>Client</Reason>

</OptOut>

</OptOuts>

Http Response Codes

Error Code	Error Description
0	Message is OK (so far). Or successful response.
-2	Account suspended. Please contact SMS Everyone for more info.
-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
-131	Campaign originator invalid. You must send from a registered origin
-132	Invalid date range
-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:

Sending SMS

Message Character Count

Scheduling SMS

Modifying, deleting & pausing a campaign

Receiving SMS

Checking Credit Balance

Add SMS Credits

Optouts/Unsubscribes

Extras

Sample HTTP Strings

HTTP Response Codes

URL Encoding

Australia

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...

Introduction

Sending SMS (MT)

HTTP Parameters to send SMS messages

Scheduling Campaigns

Parameters for Scheduling a Campaign for a later date/time

Modifying, deleting & pausing a campaign

Parameters for deleting a campaign

Parameters for pausing a campaign

Parameters for checking status of a Campaign

Message Character Counts & Unicode Messages

Receiving SMS (MO)

OPTION 1 - Receiving real time to your web service via webhook

OPTION 2 - Receiving messages on demand (2 WAY)

Retrieving All Unretrieved Replies

Retrieving All Replies for a given period

HTTP Response - CSV

HTTP Response – JSON

HTTP Response – XML

Checking SMS Credit Balance

Add SMS Credits

Optouts/Unsubscribes

Add a number to our optout database (opt out / unsubscribe)

Delete a number from our optout database (opt back in / re-subscribe)

Retrieve a list of all numbers that are opted out / unsubscribed

Extras

Time zones

Send Window

Sample HTTP Strings

Http Response Codes

URL Encoding

Why do we need URL Encoding?

How are characters URL Encoded?

What characters need to be encoded and why?

SMS HTTP API Send SMS via HTTP POST or GET

Before you start...

Introduction

Sending SMS (MT)

HTTP Parameters to send SMS messages

Scheduling Campaigns

Parameters for Scheduling a Campaign for a later date/time

Modifying, deleting & pausing a campaign

Parameters for deleting a campaign

Parameters for pausing a campaign

Parameters for checking status of a Campaign

Message Character Counts & Unicode Messages

Receiving SMS (MO)

OPTION 1 - Receiving real time to your web service via webhook

OPTION 2 - Receiving messages on demand (2 WAY)

Retrieving All Unretrieved Replies

Retrieving All Replies for a given period

HTTP Response - CSV

HTTP Response – JSON

HTTP Response – XML

Checking SMS Credit Balance

Add SMS Credits

Optouts/Unsubscribes

Add a number to our optout database (opt out / unsubscribe)

Delete a number from our optout database (opt back in / re-subscribe)

Retrieve a list of all numbers that are opted out / unsubscribed

Extras

Time zones

Send Window

Sample HTTP Strings

​

​

​

​

​

​

​

​

​

Http Response Codes

URL Encoding

Why do we need URL Encoding?

How are characters URL Encoded?

What characters need to be encoded and why?

SMS HTTP API
Send SMS via HTTP POST or GET