top of page

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

schedule sms via http api. sms http api

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

delete an sms campaign. sms http api

Parameters for pausing a campaign

pause an sms campaign. sms http api

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

​

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:

SMS API - GSM 7 character set

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

sms replies via api. sms http api

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.

sms replies for a period. sms http api

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


​

check sms credits. sms http api

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

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

add sms credits via api. sms http api

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)

unsubscribe a number. sms http api

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.

re-subscribe a number. sms http api

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=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)

 

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:

​

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

​

Url encode char - reserved characters. sms http api

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

Url encode char - unsafe characters. sms http api
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
bottom of page