SMS REST API

We have a very simple but powerful SMS REST API for sending single SMS messages and bulk SMS campaigns.

This is known as a Mobile Terminated (MT) message.

You can also receive SMS replies via this API. These are known as Mobile Originated (MO) messages.

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

if you don't have a username and password, sign up and we'll give you 100 free credits to test with.

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.

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.

 

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

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

 

POST to 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 campaign 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"

}

Response for a successfully created campaign

The JSON response object contains the following parameters:

JSON

{

    "Code": 0,

    "CampaignId": 11967222,

    "Messages": 5,

    "Segments": 1,

    "Credits": 5

}

Cancel a scheduled SMS message

To cancel/delete a campaign, submit our campaignID and the delete action. 

{

    "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. 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. 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 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 https://smseveryone.com/api/replies

If you dont add any extra fields 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 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",

      "MessageText": "Thanks, yes i will be at the appointment",

      "ReferenceId": "4499850"

    },

    {

      "Received": "2020-07-27T11:35:10",

      "Originator": "61400987654",

      "MessageText": "Can we reschedule?",

      "ReferenceId": "4499851"

    }

  ]

}

No messages available to retrieve:

{

  "Count": 0,

  "Messages": []

}

SMS Replies via 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.

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

Checking SMS Credit Balance

You can send a POST to our credit balance API to get your current balance

Request

 

POST to https://smseveryone.com/api/credits

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 9986 SMS credits remaining on the account:

{

    "Credits": 9986,

    "Code": 0

}

0 SMS credits remaining on the account:

{

    "Credits": 0,

    "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",

            "Number": "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",

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

}

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