Developer Zone | The SMS Works

Using the API

What our API is for and how to get the best out of it.

Our SMS API allows you to integrate reliable text messaging directly into your applications. There are several ways to integrate with The SMS Works to send and recieve messages. This overview will help you to decide on the best approach for each of your use-cases.

What to Send

You can send one message at a time (/message/send) or batches of messages. There are two types of batches, which allow you to send either (1) the same message to lots of people (/batch/send) or (2) a collection of unique messages personalised to your audience (/batch/any).

Messages can be sent immediately from your application, or scheduled to go out at a specific date and time. That applies to single messages and to both of the batch methods. This gives you the flexibility to tailor the message and delivery to have the most impact.

How to Send Messages

We've provided cut-and-paste snippets of code that you can use in your applications to integrate our SMS sending capabilities. You can either call our end-points directly, or use one of our Software Development Kits (SDK's), for enhanced error handling and integration with your business logic. Samples are provided for each approach.

We also provide an Email 2 SMS service, which lets you integrate SMS elsewhere into your business processes in a simple way. To integrate with popular business applications with minimal coding we can also provide access to our Zapier app.

Tracking Delivery

When you send a message with our API, we'll respond with a confirmation that the message was sent, and a message ID. Whenever the status of the message is changed by the network we'll send you and up-to-date devivery report, with all of the details. You can register a webhook on your account page to receive these delivery reports into your application.

Getting Replies

We offer SMS Reply Numbers which allow your customers to send responses to your out-going messages. You can either set up webhooks to receive these responses, or we can forward them to your preferred email address. This makes it easy to keep the conversation going, in a way that suits your technology, people and processes.

Quick Start

Get up and running

Set up a free SMS Works account
Sign in to your account and generate a JSON Web Token for authentication on the API Key tab, as shown below.
Once you have your API and we've assigned your free test credits, you can send your first test message. There are three options:
- Install one of our SDK's
- Make a regular HTTP POST to our https://api.thesmsworks.co.uk/v1/message/send end-point from your application, or using our ready-made Postman collection.
- Make a simple cURL request using the code snippet below, to send a test message.
```
curl --location --request POST 'https://api.thesmsworks.co.uk/v1/message/send'
  --header 'Content-Type: application/json'
  --header 'Authorization: Your JSON Web Token goes here'
  --data-raw '{
  "sender": "TheSMSWorks",
  "destination": "44777777777",
  "content": "My super awesome message"
}'
```

Base URL

All calls to the the SMS Works API use the base url https://api.thesmsworks.co.uk/v1

For example, to send an SMS to our '/message/send' end-point you would use the address https://api.thesmsworks.co.uk/v1/message/send

Headers

You must include both of these headers in all of your API calls:

'Content-Type' : 'application/json'
'Authorization' : 'Your JSON Web Token goes here'

You can read about obtaining a JSON Web Token in our authentication section.

Character Encoding

Message content is transmitted using the standard GSM character set. Messages using this character set can be up to 160 characters in length.

If the message sent contains any character outside the GSM alphabet, UTF-16 encoding will be applied, along with a 70-character limit on message length. This determines the number of credits used to send the message (i.e. you will be charged 1 credit per 70 characters).

Don't copy and paste content from Microsoft Word or other word processing applications. This would likely result in non-GSM characters being used and the message sent as UTF-16. Some characters, such as certain apostrophes and hyphens may appear to be in the GSM character set but actually contain subtle differences.

You can use our free unicode detector to help identify and eliminate any unicode characters in you texts.

Flooding

A 'flooding filter' is in place to prevent individuals being sent the same message repeatedly in a short space of time.

A single number can only receive 20 varied messages and 6 identical messages per hour.

Please note that in some instances the flooding filter may not prevent multiple messages being delivered to the same number. Please ensure that you're not relying on it to prevent credits being consumed. We cannot offer refunds where the flooding filter has not prevented multiple deliveries.

Also, if you have an SMS overdraft arranged and your overdraft is wholly or partially used, you are liable for the text credits used.

Preflight Checks

Things to check before your SMS integration goes live.

Check your messages use the GSM character set to avoid using more credits than expected, using our free unicode detector.
Check the SMS message length is as intended
Set up the Low Credit Warning in your SMS Works account
Whitelist our domains so that alerts and other emails can reach you: thesmsworks.co.uk, thesmsworks.net
If you have a reply number, make sure that replies are being handled correctly
Triple-check your code in all possible scenarios

This article highlights some of the more common things that are easily overlooked.

About

This sections describes each of the methods in our SMS API, with sample scripts in several languages to get you started. We also provide request and response references for each method, to help you build your integration, as well as detailed parameter definitions.

The sample code provided illustrates how you might integrate our API in to your solution, but is not certified for production environments. You are responsible for testing and QA.

API Methods

This section introduces the main methods in our SMS API, with code snippets in your preferred language to get you started. Each of the listed methods includes a link to our API Reference, where you can find details of the expected request and response, as well as more advanced methods for working with our API.

Preferred language

/message/send

POST https://api.thesmsworks.co.uk/v1/message/send

Sends a single SMS message

Open Gist API Reference

/message/schedule

POST https://api.thesmsworks.co.uk/v1/message/schedule

Shedule the delivery of a single SMS message

Open Gist API Reference

/messages/schedule/{:messageid}

DELETE https://api.thesmsworks.co.uk/v1/messages/schedule/{:messageid}

Deletes a scheduled SMS message

Open Gist API Reference

/messages

POST https://api.thesmsworks.co.uk/v1/messages

Return a list of messages matching your query

Open Gist API Reference

/message/{:messageid}

GET https://api.thesmsworks.co.uk/v1/message/{:messageid}

Returns the delivery report for a single SMS message

Open Gist API Reference

/batch/send

POST https://api.thesmsworks.co.uk/v1/batch/send

Sends a batch of identical SMS messages to multiple recipients

Open Gist API Reference

/batch/schedule

POST https://api.thesmsworks.co.uk/v1/batch/schedule

Schedules a batch of identical SMS messages to be sent to multiple recipients

Open Gist API Reference

/batches/schedule/{:batchid}

DELETE https://api.thesmsworks.co.uk/v1/batches/schedule/{:batchid}

Deletes a batch of scheduled messages

Open Gist API Reference

/batch/any

POST https://api.thesmsworks.co.uk/v1/batch/any

Sends a batch of unique SMS messages to a series of unique recipients

Open Gist API Reference

/batch/{:batchid}

GET https://api.thesmsworks.co.uk/v1/batch/{:batchid}

Returns a list of delivery reports for each message in a given batch

Open Gist API Reference

Outbound SMS

Parameter	Type	Required	Definition
sender String required	String	required	This field specifies the sender ID or originator of the message. This is who the message is from when the message arrives on the recipient's phone. The sender can be alphanumeric and must be between 3 and 11 characters. No spaces or special characters are permitted in the sender. Alternatively, the sender can be up to 15 numeric characters. This is used if you want the recipient to be able to reply to the text. If you have a reply number set up on your account, you would set the sender as this number. (e.g 07900123456) If the sender is alphanumeric, the recipient will not be able to reply to the text. Many international networks do not allow the setting of an alphanumeric sender ID. Read more about SMS Sender IDs.
destination String required	String	required	The mobile number that you're sending to. Numbers can be either in UK format, 07900123456 or International format, 447900123456. Do not start numbers with the + sign. If your account has international SMS delivery enabled, numbers must begin with the country code, then drop the leading 0 from the number. (e.g 33123456789) Do not start numbers with 00. Please note that sending texts outside the UK often costs more. Please see our international SMS pricing table.
content String required	String	required	The message itself. A standard text is 160 characters, including spaces. You can send messages of up to 1280 characters in length. Texts over 160 characters will use more than 1 credit, so please check message length before sending. Longer messages are charged at 153 characters per text; the remaining characters are used to ensure that they are re-combined into a single message when they reach the handset. Messages which contain unicode characters will be charged at 70 characters per text. Use our free SMS message length calculator to check your message length and number of SMS credits required to send the message.
deliveryreporturl String optional	String	optional	The url to which we should POST delivery reports to for this particular message. If none is specified, we'll use the global delivery report URL that you've configured on your SMS Works account page.
metadata Array of objects optional	Array of objects	optional	An array of metadata objects. This can be used to store a series of key/value pairs that allow you to assign granular information to each message you send. This good for campaign analysis or onward billing to your customers, if required. Each metadata must have 'key' and 'value' parameters, as shown in the following example: `"metadata": [{ "key": "branchGUID", "value": "e60e5f31-etc" },{ "key": "messageQueueID", "value": "9648523" }]` This will be stored in the delivery report formatted as follows, making it easy for you to query later on: `"metadata": { "branchGUID": "e60e5f31-etc", "messageQueueID": "9648523" }` Any supplied metadata will be stored on your message delivery report for retrieval and analysis. If you have an SMS Works reply number, we will forward any metadata included in the last outbound SMS message to a recipient from that Reply Number, when they reply to your message. This can be especially useful in categorising content for your team, without forcing them to go elsewhere to find that information.
responseemail Array of Strings optional	Array of Strings	optional	An optional array of email addresses to forward responses to this specific message to. An SMS Works Reply Number is required to use this feature.
schedule String optional	String	optional	The schedule date format should match the JavaScript date format, which is the same as the ISO 8601 specification, e.g Sun Sep 03 2017 15:34:23 GMT+0100 (BST).
tag String optional	String	optional	You can add a tag to each message, which can be useful for identifying all numbers that were sent a particular message or were part of the same campaign. The tag can be alphanumeric and contain spaces. The maximum number of characters is 280, including the spaces.
ttl String optional	String	optional	Time To Live. The optional number of minutes before the message is deleted, defined as an integer. Optional. Omit this parameter to prevent delivery report deletion.
validity Number optional	Number	optional	The optional number of minutes to attempt delivery before the message is marked as EXPIRED. The default is 2880 minutes (48 hours).

Inbound SMS

The parameters used to forward inbound SMS messages to your webhooks

Parameter	Type	Definition
content String	String	The content of the incoming SMS. Longer messages that are split into several parts will be concatenated by us, once we have received them all, and sent to you in one go.
from String	String	The mobile number from which the incoming SMS was sent.
messageid String	String	The unique message ID used to identify the delivery report for this message.
messagetype String	String	Hard-coded to "incoming".
parts String	String	The number of parts used to send the message. 1 message part is 160 characters.
tag String	String	The tag used on the last outbound SMS to the sender of this incoming SMS using the relevant Reply Number. Tags allow you to identify which campaign or category the incoming SMS relates to.
to String	String	The SMS Works Reply Number to which the message was sent.

Delivery Reports

The parameters used to forward inbound SMS messages to your webhooks

Parameter Type Definition

batchid

String

If the message was sent as part of a batch, the batch ID is recorded here. You can use he /batch/{:batchid} end-point to retrieve all messages in a batch.

content

String

The content of the message you sent.

contentsafe

String

The content of the message, with emojis removed. This may be easier to handle in your application than the raw content.

created

String

Date/time at which the message was sent, in ISO8601 format, e.g. 2019-11-14T00:55:31.820Z

country

String

The 2-letter country-code for the country in which the destination mobile is registered.

credits

Number

The number of SMS credits used to send the message.

destination

Number

The number of recipient handset used to send this message.

failurereason

Object

In the event that the message could not be delivered due to an error, the failurereason object records the details in three fields:

code Number The SMS error code.	Number	The SMS error code.
details String The definition of the error (why the message was not delivered).	String	The definition of the error (why the message was not delivered).
permanent Boolean If `true`, indicates that no further attempts will be made to deliver the message.	Boolean	If `true`, indicates that no further attempts will be made to deliver the message.

flash

Boolean

If true, the message was sent as a flash message, using our /message/flash end-point.

identifier

String

The number supplied when you sent the message, which we parse before sending. This can be useful when identifying issues in your data.

international

Boolean

If true, the message was sent to a country outside of the United Kingdom. Use this in combination with the 'identifier' and 'country' paramters to confirm that you are formatting destination numbers correctly.

keyword

String

For incoming messages to our 88440 shortcode, the Keyword used in the message.

messageid

String

The unique ID of the message.

messageparts

String

The number of SMS messages used to send the complete message to the recipient. This can be used to refine your message content, to remove unicode characters or limit the number of characters in future messages.

Use our SMS testing tools to optimise your messages before you sned your campaigns.

modified

String

The date/time at which this delivery report was last updated. Modification occurs whenever we receive message status updates from the relevant mobile network.

responseemail

Array of Strings

The list of the email addresses to which we will forward any replies to this message. If none is specified, we will default to the optional Response Email address configured in your SMS Works Account.

schedule

String

The date/time at which this message was scheduled to be sent. This is specified by you when using our /message/schedule end-point, otherwise it defaults to the same value as the 'created' parameter.

sender

String

The Sender ID used to send the message.

status

String

The status of the message. Read further documentation on SMS Status & Error Codes.

tag

String

The optional tag used to identify the message when it was sent.

ttl

Number

The Time To Live, in minutes, specified when the message was sent. Once any specified TTL expires, the delivery report will be deleted.

unread

Boolean

For incoming messages, identifies whether the message has been previously retrieved using the /messages/inbox end-point.

validity

Number

The time, in minutes, specified to define the number of minutes to attempt delivery before the message is marked as EXPIRED. The default is 2880 minutes (48 hours).

API Error Codes

These errors are returned by our API in the event that your message could not be sent.

Bad Message Content Errors (http 400)

Code	Error Message	Notes
4001	Message length is 0 characters. Cannot send message. Please check and try again.
4002	Cannot send messages longer than 1280 characters.	You can send messages up to 1280 characters in length.
4003	Sender ID length invalid.	Please use 3 - 11 characters maximum length for alphanumeric sender IDs or 3 - 15 digits maximum length for numeric sender IDs.
4004	Invalid destination number.	We were not able to determine a valid UK or international destination number.
4005	Tag longer than 280 characters.	The maximum length of a tag is 280 characters, including spaces.
4006	Message contains profanity.	Profane language has been detected in the content of the message. Message not sent.
4007	Message contains blocked terms. Account disabled.	The message contains terms that match our phishing filters. Your account has been disabled as a precaution.
4008	Invalid message ID.	Returned when an invalid message ID is supplied to the `/message/{:messageid}` method.
4009	Invalid date/time supplied	Returned by the message scheduler if an invalid date, or a date in the past is supplied.

Authentication Errors (http 401)

Code	Error Message	Notes
4011	Not authenticated.	This error is returned if you supply an invalid API Key/Secret pair when obtaining a JSON Web Token.

Credit Errors (http 402)

Code	Error Message	Notes
4021	Insufficient credit to send message.	Please add more credits to your account in order to continue sending messages.

Authorisation Errors (http 403)

Code	Error Message	Notes
4031 / 4032	Not authorised.	The account was not found. Cannot send messages.
4033	Account disabled.	The account was not prevented from sending SMS after triggering one of our spam filters.
4034	This account is not enabled for international SMS.	Your message was addressed to an international mobile number, but your account is not enabled to send international SMS. Please contact [email protected] for assistance.

Delivery Status

For every text message that is sent through the SMS API, a delivery report is generated that provides detailed information on the delivery status of the SMS. Each time the status of the message is updated, we'll forward the delivery report to the webhook URL specified in your account.

This section, along with the one below, detail the possible delivery report statuses and associated error codes, in the event that a message could not be delivered.

If a UK message cannot be successfully delivered we will refund the relevant number of SMS credits to your account and you will not be charged. Many international mobile networks do not offer SMS delivery reports to anything like the detail or reliability of UK networks, thus failed international messages cannot be refunded.

Status	Description
SENT	The message has been accepted and passed to the network for delivery to the handset. We have yet to receive a futher update on the delivery status.
DELIVERED	Mobile number is valid and the message has been successfully delivered to the handset.
UNDELIVERABLE	The message could not be delivered (see below for possible reasons why a message might be undelivered). For UK SMS, the text credit is refunded to your account.
EXPIRED	The message was not delivered within the expressed validity period. By default, this is 2880 minutes (48 hours). You can specify a shorter validity period, in minutes, using the relevant parameter in our SMS API. This can be helpful if you need to take alternative action in the event that your message could not be delivered.
REJECTED	The message was rejected by the network (see below for additional detail).

Delivery Report Error Codes

Text messages may not be delivered for a wide variety of reaasons. We've simplified our error reporting, grouping them in to simple codes that you can build logic or reporting around, to help you quickly identify why your messages have not been delivered.

If an error is recorded as being 'permanent' then the message will not be delivered. If it is not permanent the message may still be delivered within the expiry period described above.

This information will be forwarded to your delivery report webhook URL in the failurereason object, and will be available in report exports and from our /messages and /messages/{:messageid} API end-points.

Please note that due to very large file sizes, delivery reports are available for 3 months, after which they are permanently deleted. If you need access to historical delivery data, please ensure you download reports before they expire.

Please be aware that the sms delivery report service offered by the networks comes with no guarantees, service level agreements or contracts.

Code	Details	Permanent
5001	Handset Error: Number does not exist or has not been assigned to a user.	true
5004	Message has been sent to the operator but the request was rejected, or a delivery report with status REJECTED was reverted.	true
5006	Handset Error: No response. Handset may be switched off or in a low signal area.	true
5008	Handset Error: Roaming not allowed.	true
5009	Message has been sent to the operator, but has failed to deliver, since a delivery report with status UNDELIVERED was reverted from the operator.	true
5010	Message has been received and rejected due to the user being subscribed to DND (Do Not Disturb) services, disabling any service traffic to their number.	true
5011	The subscriber's mobile service has been suspended by the operator.	true
5013	Handset Error: Device is set to Do Not Disturb (DND). In this instance the message may still be delivered if the DND setting is removed within the validity period of the message.	false
5015	The message was received and sent to the operator. However, it has been pending until the validity period has expired, or the operator returned EXPIRED status in the meantime.	false
5020	Message has been rejected due to an anti-flooding mechanism. By default, a single number can only receive 20 varied messages and 6 identical messages per hour.	true
5034	Handset Error: System failure.	true

API Service Errors

Errors returned if the SMS Works experiences an internal system error.

In the event of a system outage, http 504 or 503 errors will be returned by either our firewall or load balancers.

Internal Server Errors (http 500)

Code	Error Message	Notes
5002	SMS Works database problem. Your scheduled message could not be stored for delivery.	Please contact [email protected] if this error persists.

Due to large file sizes, delivery reports are retained on our system for 3 months. If you wish to refer to reports that are older than this please ensure that you use the reporting tools in your account to download them before they are removed.

Webhooks

You'll want to keep track of whether your messages have been delivered or not, so that you can monitor campaigns, keep records up to date and of course, track your spend.

We will make an HTTP POST for each delivery report to the URL end-point that you specify on your account page. You will need to write code to handle these reports, if you wish to do so automatically. Historical delivery reports can also be exported from the Delivery Reports tab on the same page.

Due to very large file sizes, delivery reports are available for 3 months, after which they are permanently deleted. If you need access to historical delivery data, please ensure you download reports before they expire.

For messages which fail to be delivered, or are rejected, we record the details of SMS delivery error messages in the 'failurereason' object on the delivery report.

Schema

Delivery reports are JSON objects, with a format as shown below.

Details of each parameter can be found in our Delivery Report parameter definitions.

{
	"batchid": "",
	"content": "del rep structure confirmation",
	"contentsafe": "del rep structure confirmation",
	"country": "GB",
	"created": "2022-06-15T10:23:26.226Z",
	"credits": 1,
	"customerid": "your-customer-id-is-found-here",
	"destination": 447484777777,
	"failurereason": {
		"code": 5001,
		"details": "Handset Error: Number does not exist or has not been assigned to a user.",
		"permanent": true
	},
	"flash": false,
	"identifier": "07484777777",
	"international": false,
	"keyword": "",
	"messageid": "d87e93c0-fa08-4903-becd-aeb5b0ab3b6a",
	"messageparts": 1,
	"modified": "2022-06-15T10:31:52.259Z",
	"responseemail": [
		"[email protected]"
	],
	"schedule": "2022-06-15T10:23:26.199Z",
	"sender": "TheSMSWorks",
	"status": "REJECTED",
	"tag": "",
	"ttl": 0,
	"unread": true,
	"validity": 2880
}

Developers

Using the API

What to Send

How to Send Messages

Tracking Delivery

Getting Replies

Quick Start

Authenticating API calls

Token Management

Base URL

Headers

Character Encoding

Flooding

Preflight Checks

About

API Methods

/message/send

/message/schedule

/messages/schedule/{:messageid}

/messages

/message/{:messageid}

/batch/send

/batch/schedule

/batches/schedule/{:batchid}

/batch/any

/batch/{:batchid}

Outbound SMS

​​​ Inbound SMS

​​​ Delivery Reports

API Error Codes

Bad Message Content Errors (http 400)

Authentication Errors (http 401)

Credit Errors (http 402)

Authorisation Errors (http 403)

​​​ Delivery Status

​​​ Delivery Report Error Codes

​​​ API Service Errors

Internal Server Errors (http 500)

Webhooks

​​​ Schema

Developer SDK's

Inbound SMS

Delivery Reports

Delivery Status

Delivery Report Error Codes

API Service Errors

Schema