The SMS Works Developer Zone
Integrate SMS into your app, software or website in minutes
Quick Start
There are just a few simple steps to integrate The SMS Works service into your application, software of website.
1 Open a free account with 50 free SMS credits pre-loaded
2 Set up authentication – see below
3 Use our simple methods to send and receive messages
You can write your own wrapper around our REST API calls or download one of our SDKs to get started quickly, in your preferred language.
Our brief technical overview provides a performance, reliability and security outline of our SMS API platform.
Check our SMS pricing page. Once you've completed integration, you can buy SMS credits from as little as 1.45 pence with our credit doubling offer.
Once you've set up authentication you can begin testing with our API right away using Postman. Just click the Run in Postman button below to import a collection containing our methods, then add your JSON Web Token to the Authorization header and get cracking.
Content Types
All requests and responses to and from the SMS Works API are in JSON format, and should contain the header 'Content-Type="application/json"'.
This quick start guide provides copy & paste code examples that you can use with our SDKs in your applications. Our API Reference details the required formats for each request, as well as describing what responses to expect and the related error codes for each call.
Character Encoding
Message content is transmitted using the standard gsm character set.
If the message sent contains any character outside the GSM alphabet, UTF-16 encoding will apply, along with a 70 character limit on message length. This is reflected in the number of credits used to send the message (i.e. we will charge you 1 credit per 70 characters; typically double for international messages).
Do not 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.
Authentication
Set up
The SMS Works uses JSON Web Tokens (JWT) for authentication. Follow these steps to set up authentication:
- Set up a free account. Your account comes with 50 free messages. Let us know if you need more.
- From your account page, generate an API Key & Secret from the ' API Key' tab.
- Take the API Key & Secret, along with your Customer ID (which is on your account page), and make a POST call to the token endpoint - https://api.thesmsworks.co.uk/v1/auth/token. This will generate a new JSON Web Token.We like to use POSTMAN for generating tokens, as it saves you from having to write code just to get things up and running. See the screenshot below with the token call shown.
- You're ready to make calls to The SMS Works API. The full JSON Web Token (the "token" value in the above screenshot) should be passed in the 'Authorization' header with all calls.Keep your token safe and secure; anyone who has access to it can use it to send messages from your account. If your token is compromised you can renew it. See 'Renewing JSON Web Tokens' below.
Renewing JSON Web Tokens
Any SMS Works JSON Web Token that you generate will never expire on its own. That means, for example, if your application sends out alerts once in a while, your token will continue to work, and you don't need to come back periodically to generate a new one, or write extra code to handle token expiry.
There may be times when you'd like to renew your token, when a developer leaves the company, for example, or if you're worried that someone else may have obtained access to it. It may just be your company's policy to refresh these things periodically.
Renewing a token is simple. Just generate a new API Key & Secret from your account page.
This immediately invalidates any tokens that you have previously generated. Use the new API Key & Secret to generate a new token and start using that in your application. Job done.
Flooding Filter
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 are 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 will be liable for the used text credits.
Parameter Definitions
Parameter |
Definition |
|
|---|---|---|
Sender |
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) Please note that if the sender is alphanumeric, the recipient will not be able to reply to the text. |
|
Destination |
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 is set to international, 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 uses 2 text credits and non delivered texts are not refunded. |
|
Content |
The message itself. |
|
Message length |
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. |
|
Tag |
You can add a tag to each message which can be useful for identifying all numbers that were sent a particular message or are part of the same campaign. The tag can be alphanumeric and contain spaces. The maximum number of characters is 280, including spaces. |
|
Schedule Date |
The schedule date format should match the JavaScript date format, which is the same as the ISO 8601 syntax. E.g |
|
Credit Management |
Your account will no longer send messages when your account runs out of SMS credits. You can set up a low credit warning email alert in your account under Low Credit Warning. |
|
Caution – Some users choose to place their request in a code loop for testing. Please be very careful that all credits are not consumed very quickly. Unfortunately, we can’t refund text credits that have been used in this way.
Sending Messages
The following sections provide copy & paste code, from each of our SDKs, for each of the services in our Message API. We also provide a link to the relevant format description in our API Reference.
Message API
All calls to the Message API use the base url https://api.thesmsworks.co.uk/v1
Messages can be sent either one at a time, or in batches to several recipients at once. Both single and batch messages can be scheduled to be sent at the time of your choosing.
Our example code is an illustration of how you might integrate with our systems and is not certified for production environments. You are responsible for testing and QA.
POST /message/send
Sends an SMS Message
// Requires SMS Works C# SDK
using System;
using System.Diagnostics;
using IO.Swagger.Api;
using IO.Swagger.Client;
using IO.Swagger.Model;
namespace Example
{
public class SendMessageExample
{
public void main()
{
// Configure API key authorization: JWT
Configuration.Default.ApiKey.Add("Authorization", "YOUR_API_KEY");
var apiInstance = new MessagesApi();
var smsMessage = new Message( // Message | Message properties
Sender = "AcmePizza",
Destination = "07777777777",
Content = "My super awesome message",
Schedule = "",
Tag = "Campaign1"
);
try
{
SendMessageResponse result = apiInstance.SendMessage(smsMessage);
Debug.WriteLine(result);
}
catch (Exception e)
{
Debug.Print("Exception when calling MessagesApi.SendMessage: " + e.Message );
}
}
}
}
/* Requires SMS Works Java SDK */
// Import classes:
//import io.swagger.client.ApiClient;
//import io.swagger.client.ApiException;
//import io.swagger.client.Configuration;
//import io.swagger.client.auth.*;
//import io.swagger.client.api.MessagesApi;
import java.util.Date;
import java.text.SimpleDateFormat;
ApiClient defaultClient = Configuration.getDefaultApiClient();
// Configure API key authorization: JWT
ApiKeyAuth JWT = (ApiKeyAuth) defaultClient.getAuthentication("JWT");
JWT.setApiKey("YOUR API KEY");
MessagesApi apiInstance = new MessagesApi();
Message smsMessage = new Message(); // Message | Message properties
smsMessage.setSender("AcmeCorp");
smsMessage.setDestination("07777777777");
smsMessage.setContent("My super awesome message");
smsMessage.setSchedule("");
smsMessage.setTag("AcmeCampaign1");
try {
SendMessageResponse result = apiInstance.sendMessage(smsMessage);
System.out.println(result);
} catch (ApiException e) {
System.err.println("Exception when calling MessagesApi#sendMessage");
e.printStackTrace();
}
var TheSmsWorksApi = require('the_sms_works_api');
var defaultClient = TheSmsWorksApi.ApiClient.instance;
// Configure API key authorization: JWT
var JWT = defaultClient.authentications['JWT'];
JWT.apiKey = 'YOUR API KEY';
var apiInstance = new TheSmsWorksApi.MessagesApi();
var smsMessage = new TheSmsWorksApi.Message(); // Message | Message properties
smsMessage.sender = "AcmeCorp";
smsMessage.destination = 07777777777;
smsMessage.content = 'My super awesome message';
smsMessage.schedule = '';
smsMessage.tag = "campaign1";
var callback = function(error, data, response) {
if (error) {
console.error(error);
} else {
console.log('API called successfully. Returned data: ' + data);
}
};
apiInstance.sendMessage(smsMessage, callback);
<!?php
/* requires SMS Works PHP SDK */
require_once(__DIR__ . '/vendor/autoload.php');
// Configure API key authorization: JWT
$config = \Swagger\Client\Configuration::getDefaultConfiguration()->setApiKey('Authorization', 'Your JSON Web Token goes here');
$apiInstance = new \Swagger\Client\Api\MessagesApi(
new \GuzzleHttp\Client(),
$config
);
$sender = 'MyCompany';
$destination = '07777777777';
$content = 'My super awesome message';
$schedule = '';
$data = array("sender"=>$sender,"destination"=>$destination,"content"=>$content,"schedule"=>$schedule);
$sms_message = new \Swagger\Client\Model\Message($data);
try {
$result = $apiInstance->sendMessage($sms_message);
print_r($result);
} catch (Exception $e) {
echo 'Exception when calling MessagesApi->sendMessage: ', $e->getMessage(), PHP_EOL;
}
?>
from __future__ import print_function
import time
import swagger_client
from swagger_client.rest import ApiException
from pprint import pprint
# Configure API key authorization: JWT
swagger_client.configuration.api_key['Authorization'] = 'YOUR_API_KEY'
# create an instance of the API class
api_instance = swagger_client.MessagesApi()
sms_message = swagger_client.Message() # Message | Message properties
sms_message.sender = "AcmeCorp"
sms_message.destination = "07777777777"
sms_message.content = "My super awesome message"
sms_message.schedule = ""
sms_message.tag = "AcmeCampaign1"
try:
api_response = api_instance.send_message(sms_message)
pprint(api_response)
except ApiException as e:
print("Exception when calling MessagesApi->send_message: %s\n" % e)
# load the gem
require 'swagger_client'
# setup authorization
SwaggerClient.configure do |config|
# Configure API key authorization: JWT
config.api_key['Authorization'] = 'YOUR API KEY'
end
api_instance = SwaggerClient::MessagesApi.new
sms_message = SwaggerClient::Message.new # Message | Message properties
smsMessage.sender = "AcmePizza"
smsMessage.destination = "07777777777"
smsMessage.content = "My super awesome message"
smsMessage.schedule = ""
smsMessage.tag = "Campaign1"
begin
result = api_instance.send_message(sms_message)
p result
rescue SwaggerClient::ApiError => e
puts "Exception when calling MessagesApi->send_message: #{e}"
end
POST /message/schedule
Schedules an SMS message to be sent at the date-time you specify
// Requires SMS Works C# SDK
using System;
using System.Diagnostics;
using IO.Swagger.Api;
using IO.Swagger.Client;
using IO.Swagger.Model;
namespace Example
{
public class ScheduleMessageExample
{
public void main()
{
// Configure API key authorization: JWT
Configuration.Default.ApiKey.Add("Authorization", "YOUR_API_KEY");
var apiInstance = new MessagesApi();
var smsMessage = new Message( // Message | Message properties
Sender = "AcmePizza",
Destination = "07777777777",
Content = "My super awesome message",
Schedule = DateTimeOffset.Now.ToString("o"),
Tag = "Campaign1"
);
try
{
ScheduledMessageResponse result = apiInstance.ScheduleMessage(smsMessage);
Debug.WriteLine(result);
}
catch (Exception e)
{
Debug.Print("Exception when calling MessagesApi.ScheduleMessage: " + e.Message );
}
}
}
}
/* Requires SMS Works Java SDK */
// Import classes:
//import io.swagger.client.ApiClient;
//import io.swagger.client.ApiException;
//import io.swagger.client.Configuration;
//import io.swagger.client.auth.*;
//import io.swagger.client.api.MessagesApi;
import java.util.Date;
import java.text.SimpleDateFormat;
ApiClient defaultClient = Configuration.getDefaultApiClient();
// Configure API key authorization: JWT
ApiKeyAuth JWT = (ApiKeyAuth) defaultClient.getAuthentication("JWT");
JWT.setApiKey("YOUR API KEY");
MessagesApi apiInstance = new MessagesApi();
Message smsMessage = new Message(); // Message | Message properties
smsMessage.setSender("AcmeCorp");
smsMessage.setDestination("07777777777");
smsMessage.setContent("My super awesome message");
smsMessage.setSchedule(new SimpleDateFormat("EEE MMM dd hh:mm:ss yyyy").format(new Date()));
smsMessage.setTag("AcmeCampaign1");
try {
SendMessageResponse result = apiInstance.scheduleMessage(smsMessage);
System.out.println(result);
} catch (ApiException e) {
System.err.println("Exception when calling MessagesApi#scheduleMessage");
e.printStackTrace();
}
var TheSmsWorksApi = require('the_sms_works_api');
var defaultClient = TheSmsWorksApi.ApiClient.instance;
// Configure API key authorization: JWT
var JWT = defaultClient.authentications['JWT'];
JWT.apiKey = 'YOUR API KEY';
var apiInstance = new TheSmsWorksApi.MessagesApi();
var smsMessage = new TheSmsWorksApi.Message(); // Message | Message properties
smsMessage.sender = "AcmeCorp";
smsMessage.destination = 07777777777;
smsMessage.content = 'My super awesome message';
smsMessage.schedule = new Date('October 14, 2016 17:00:00');
smsMessage.tag = "campaign1";
var callback = function(error, data, response) {
if (error) {
console.error(error);
} else {
console.log('API called successfully. Returned data: ' + data);
}
};
apiInstance.scheduleMessage(smsMessage, callback);
<?php
require_once(__DIR__ . '/vendor/autoload.php');
// Configure API key authorization: JWT
Swagger\Client\Configuration::getDefaultConfiguration()->setApiKey('Authorization', 'YOUR_API_KEY');
$api_instance = new Swagger\Client\Api\MessagesApi();
$sms_message = new \Swagger\Client\Model\Message(); // \Swagger\Client\Model\Message | Message properties
try {
$result = $api_instance->scheduleMessage($sms_message);
print_r($result);
} catch (Exception $e) {
echo 'Exception when calling MessagesApi->scheduleMessage: ', $e->getMessage(), PHP_EOL;
}
?>
from __future__ import print_function
import time
import swagger_client
from swagger_client.rest import ApiException
from pprint import pprint
# Configure API key authorization: JWT
swagger_client.configuration.api_key['Authorization'] = 'YOUR_API_KEY'
# create an instance of the API class
api_instance = swagger_client.MessagesApi()
sms_message = swagger_client.Message() # Message | Message properties
d = datetime.now(timezone.utc)
sms_message.sender = "AcmeCorp"
sms_message.destination = "07777777777"
sms_message.content = "My super awesome message"
sms_message.schedule = d.strftime('%a %d %b %Y %H:%M:%S %Z')
sms_message.tag = "AcmeCampaign1"
try:
api_response = api_instance.schedule_message(sms_message)
pprint(api_response)
except ApiException as e:
print("Exception when calling MessagesApi->schedule_message: %s\n" % e)
# load the gem
require 'swagger_client'
# setup authorization
SwaggerClient.configure do |config|
# Configure API key authorization: JWT
config.api_key['Authorization'] = 'YOUR API KEY'
end
api_instance = SwaggerClient::MessagesApi.new
sms_message = SwaggerClient::Message.new # Message | Message properties
smsMessage.sender = "AcmePizza"
smsMessage.destination = "07777777777"
smsMessage.content = "My super awesome message"
smsMessage.schedule = Time.now.utc.iso8601
smsMessage.tag = "Campaign1"
begin
result = api_instance.schedule_message(sms_message)
p result
rescue SwaggerClient::ApiError => e
puts "Exception when calling MessagesApi->schedule_message: #{e}"
end
POST /messages
Get messages matching your search criteria
// Requires SMS Works C# SDK
using System;
using System.Diagnostics;
using IO.Swagger.Api;
using IO.Swagger.Client;
using IO.Swagger.Model;
namespace Example
{
public class GetMessagesExample
{
public void main()
{
// Configure API key authorization: JWT
Configuration.Default.ApiKey.Add("Authorization", "YOUR_API_KEY");
var apiInstance = new MessagesApi();
var query = new Query( // Query
Status = "DELIVERED",
Sender = "AcmePizza",
Destination = "07777777777",
Keyword = "PIZZA",
Tag = "Campaign1",
From = DateTimeOffset.Now.ToString("o"),
To = DateTimeOffset.Now.ToString("o")
);
try
{
MessagesResponse result = apiInstance.GetMessages(query);
Debug.WriteLine(result);
}
catch (Exception e)
{
Debug.Print("Exception when calling MessagesApi.GetMessages: " + e.Message );
}
}
}
}
/* Requires SMS Works Java SDK */
// Import classes:
//import io.swagger.client.ApiClient;
//import io.swagger.client.ApiException;
//import io.swagger.client.Configuration;
//import io.swagger.client.auth.*;
//import io.swagger.client.api.MessagesApi;
import java.util.Date;
import java.text.SimpleDateFormat;
ApiClient defaultClient = Configuration.getDefaultApiClient();
// Configure API key authorization: JWT
ApiKeyAuth JWT = (ApiKeyAuth) defaultClient.getAuthentication("JWT");
JWT.setApiKey("YOUR API KEY");
MessagesApi apiInstance = new MessagesApi();
Query query = new Query(); // Query |
query.setStatus("DELIVERED");
query.setDestination("07777777777");
query.setSender("AcmeCorp");
query.setKeyword("HOLIDAYSPECIAL");
query.setFrom(new SimpleDateFormat("EEE MMM dd hh:mm:ss yyyy").format(new Date()));
query.setTo(new SimpleDateFormat("EEE MMM dd hh:mm:ss yyyy").format(new Date()));
try {
MessagesResponse result = apiInstance.getMessages(query);
System.out.println(result);
} catch (ApiException e) {
System.err.println("Exception when calling MessagesApi#getMessages");
e.printStackTrace();
}
var TheSmsWorksApi = require('the_sms_works_api');
var defaultClient = TheSmsWorksApi.ApiClient.instance;
// Configure API key authorization: JWT
var JWT = defaultClient.authentications['JWT'];
JWT.apiKey = 'YOUR API KEY';
var apiInstance = new TheSmsWorksApi.MessagesApi();
var query = new TheSmsWorksApi.Query(); // Query |
query.status = 'DELIVERED';
query.destination = 07777777777;
query.sender = 'AcmeCorp';
query.keyword = 'PIZZA';
query.from = new Date('October 14, 2016 17:00:00');
query.to = new Date('March 26, 2018 13:00:00');
var callback = function(error, data, response) {
if (error) {
console.error(error);
} else {
console.log('API called successfully. Returned data: ' + data);
}
};
apiInstance.getMessages(query, callback);
<?php
require_once(__DIR__ . '/vendor/autoload.php');
// Configure API key authorization: JWT
Swagger\Client\Configuration::getDefaultConfiguration()->setApiKey('Authorization', 'YOUR_API_KEY');
$api_instance = new Swagger\Client\Api\MessagesApi();
$query = new \Swagger\Client\Model\Query(); // \Swagger\Client\Model\Query |
try {
$result = $api_instance->getMessages($query);
print_r($result);
} catch (Exception $e) {
echo 'Exception when calling MessagesApi->getMessages: ', $e->getMessage(), PHP_EOL;
}
?>
from __future__ import print_function
import time
import swagger_client
from swagger_client.rest import ApiException
from pprint import pprint
# Configure API key authorization: JWT
swagger_client.configuration.api_key['Authorization'] = 'YOUR_API_KEY'
# create an instance of the API class
api_instance = swagger_client.MessagesApi()
query = swagger_client.Query() # Query |
d = datetime.now(timezone.utc)
query.status = "DELIVERED"
query.destination = "07777777777"
query.sender = "AcmeCorp"
query.keyword = "HOLIDAYSPECIAL"
query._from = d.strftime('%a %d %b %Y %H:%M:%S %Z')
query.to = d.strftime('%a %d %b %Y %H:%M:%S %Z')
try:
api_response = api_instance.get_messages(query)
pprint(api_response)
except ApiException as e:
print("Exception when calling MessagesApi->get_messages: %s\n" % e)
# load the gem
require 'swagger_client'
# setup authorization
SwaggerClient.configure do |config|
# Configure API key authorization: JWT
config.api_key['Authorization'] = 'YOUR API KEY'
end
api_instance = SwaggerClient::MessagesApi.new
query = SwaggerClient::Query.new # Query |
query.status = "DELIVERED"
query.sender = "AcmePizza"
query.destination = "07777777777"
query.keyword = "PIZZA"
query.tag = "Campaign1"
query.from = Time.now.utc.iso8601
query.to = Time.now.utc.iso8601
begin
result = api_instance.get_messages(query)
p result
rescue SwaggerClient::ApiError => e
puts "Exception when calling MessagesApi->get_messages: #{e}"
end
GET /messages/{messageid}
Retrieve a delivery report for the given message ID
// Requires SMS Works C# SDK
using System;
using System.Diagnostics;
using IO.Swagger.Api;
using IO.Swagger.Client;
using IO.Swagger.Model;
namespace Example
{
public class GetMessageByIdExample
{
public void main()
{
// Configure API key authorization: JWT
Configuration.Default.ApiKey.Add("Authorization", "YOUR_API_KEY");
var apiInstance = new MessagesApi();
var messageid = messageid_example; // string | The ID of the message you would like returned
try
{
MessageResponse result = apiInstance.GetMessageById(messageid);
Debug.WriteLine(result);
}
catch (Exception e)
{
Debug.Print("Exception when calling MessagesApi.GetMessageById: " + e.Message );
}
}
}
}
/* Requires SMS Works Java SDK */
// Import classes:
//import io.swagger.client.ApiClient;
//import io.swagger.client.ApiException;
//import io.swagger.client.Configuration;
//import io.swagger.client.auth.*;
//import io.swagger.client.api.MessagesApi;
ApiClient defaultClient = Configuration.getDefaultApiClient();
// Configure API key authorization: JWT
ApiKeyAuth JWT = (ApiKeyAuth) defaultClient.getAuthentication("JWT");
JWT.setApiKey("YOUR API KEY");
MessagesApi apiInstance = new MessagesApi();
String messageid = "messageid_example"; // String | The ID of the message you would like returned
try {
MessageResponse result = apiInstance.getMessageById(messageid);
System.out.println(result);
} catch (ApiException e) {
System.err.println("Exception when calling MessagesApi#getMessageById");
e.printStackTrace();
}
var TheSmsWorksApi = require('the_sms_works_api');
var defaultClient = TheSmsWorksApi.ApiClient.instance;
// Configure API key authorization: JWT
var JWT = defaultClient.authentications['JWT'];
JWT.apiKey = 'YOUR API KEY';
var apiInstance = new TheSmsWorksApi.MessagesApi();
var messageid = "messageid_example"; // String | The ID of the message you would like returned
var callback = function(error, data, response) {
if (error) {
console.error(error);
} else {
console.log('API called successfully. Returned data: ' + data);
}
};
apiInstance.getMessageById(messageid, callback);
<?php
require_once(__DIR__ . '/vendor/autoload.php');
// Configure API key authorization: JWT
Swagger\Client\Configuration::getDefaultConfiguration()->setApiKey('Authorization', 'YOUR_API_KEY');
$api_instance = new Swagger\Client\Api\MessagesApi();
$messageid = "messageid_example"; // string | The ID of the message you would like returned
try {
$result = $api_instance->getMessageById($messageid);
print_r($result);
} catch (Exception $e) {
echo 'Exception when calling MessagesApi->getMessageById: ', $e->getMessage(), PHP_EOL;
}
?>
from __future__ import print_function
import time
import swagger_client
from swagger_client.rest import ApiException
from pprint import pprint
# Configure API key authorization: JWT
swagger_client.configuration.api_key['Authorization'] = 'YOUR_API_KEY'
# create an instance of the API class
api_instance = swagger_client.MessagesApi()
messageid = 'messageid_example' # str | The ID of the message you would like returned
try:
api_response = api_instance.get_message_by_id(messageid)
pprint(api_response)
except ApiException as e:
print("Exception when calling MessagesApi->get_message_by_id: %s\n" % e)
# load the gem
require 'swagger_client'
# setup authorization
SwaggerClient.configure do |config|
# Configure API key authorization: JWT
config.api_key['Authorization'] = 'YOUR API KEY'
end
api_instance = SwaggerClient::MessagesApi.new
messageid = "messageid_example" # String | The ID of the message you would like returned
begin
result = api_instance.get_message_by_id(messageid)
p result
rescue SwaggerClient::ApiError => e
puts "Exception when calling MessagesApi->get_message_by_id: #{e}"
end
DELETE /messages/schedule/{messageid}
Cancels a scheduled SMS message
// Requires SMS Works C# SDK
using System;
using System.Diagnostics;
using IO.Swagger.Api;
using IO.Swagger.Client;
using IO.Swagger.Model;
namespace Example
{
public class CancelScheduledJobExample
{
public void main()
{
// Configure API key authorization: JWT
Configuration.Default.ApiKey.Add("Authorization", "YOUR_API_KEY");
var apiInstance = new MessagesApi();
var messageid = messageid_example; // string | The ID of the message you would like returned
try
{
CancelledMessageResponse result = apiInstance.CancelScheduledJob(messageid);
Debug.WriteLine(result);
}
catch (Exception e)
{
Debug.Print("Exception when calling MessagesApi.CancelScheduledJob: " + e.Message );
}
}
}
}
/* Requires SMS Works Java SDK */
// Import classes:
//import io.swagger.client.ApiClient;
//import io.swagger.client.ApiException;
//import io.swagger.client.Configuration;
//import io.swagger.client.auth.*;
//import io.swagger.client.api.MessagesApi;
ApiClient defaultClient = Configuration.getDefaultApiClient();
// Configure API key authorization: JWT
ApiKeyAuth JWT = (ApiKeyAuth) defaultClient.getAuthentication("JWT");
JWT.setApiKey("YOUR API KEY");
MessagesApi apiInstance = new MessagesApi();
String messageid = "messageid_example"; // String | The ID of the message you would like returned
try {
CancelledMessageResponse result = apiInstance.cancelScheduledJob(messageid);
System.out.println(result);
} catch (ApiException e) {
System.err.println("Exception when calling MessagesApi#cancelScheduledJob");
e.printStackTrace();
}
var TheSmsWorksApi = require('the_sms_works_api');
var defaultClient = TheSmsWorksApi.ApiClient.instance;
// Configure API key authorization: JWT
var JWT = defaultClient.authentications['JWT'];
JWT.apiKey = 'YOUR API KEY';
var apiInstance = new TheSmsWorksApi.MessagesApi();
var messageid = "messageid_example"; // String | The ID of the message you would like returned
var callback = function(error, data, response) {
if (error) {
console.error(error);
} else {
console.log('API called successfully. Returned data: ' + data);
}
};
apiInstance.cancelScheduledJob(messageid, callback);
<?php
require_once(__DIR__ . '/vendor/autoload.php');
// Configure API key authorization: JWT
Swagger\Client\Configuration::getDefaultConfiguration()->setApiKey('Authorization', 'YOUR_API_KEY');
$api_instance = new Swagger\Client\Api\MessagesApi();
$messageid = "messageid_example"; // string | The ID of the message you would like returned
try {
$result = $api_instance->cancelScheduledJob($messageid);
print_r($result);
} catch (Exception $e) {
echo 'Exception when calling MessagesApi->cancelScheduledJob: ', $e->getMessage(), PHP_EOL;
}
?>
from __future__ import print_function
import time
import swagger_client
from swagger_client.rest import ApiException
from pprint import pprint
# Configure API key authorization: JWT
swagger_client.configuration.api_key['Authorization'] = 'YOUR_API_KEY'
# create an instance of the API class
api_instance = swagger_client.MessagesApi()
messageid = 'messageid_example' # str | The ID of the message you would like returned
try:
api_response = api_instance.cancel_scheduled_job(messageid)
pprint(api_response)
except ApiException as e:
print("Exception when calling MessagesApi->cancel_scheduled_job: %s\n" % e)
# load the gem
require 'swagger_client'
# setup authorization
SwaggerClient.configure do |config|
# Configure API key authorization: JWT
config.api_key['Authorization'] = 'YOUR API KEY'
end
api_instance = SwaggerClient::MessagesApi.new
messageid = "messageid_example" # String | The ID of the message you would like returned
begin
result = api_instance.cancel_scheduled_job(messageid)
p result
rescue SwaggerClient::ApiError => e
puts "Exception when calling MessagesApi->cancel_scheduled_job: #{e}"
end
POST /batch/send
Send a single SMS message to multiple recipients. Sending to multiple numbers is limited to 500 recipients.
// Requires SMS Works C# SDK
using System;
using System.Diagnostics;
using IO.Swagger.Api;
using IO.Swagger.Client;
using IO.Swagger.Model;
namespace Example
{
public class SendBatchExample
{
public void main()
{
// Configure API key authorization: JWT
Configuration.Default.ApiKey.Add("Authorization", "YOUR_API_KEY");
var apiInstance = new BatchMessagesApi();
var smsMessage = new BatchMessage( // BatchMessage | Message properties
Sender = "AcmePizza",
Destinations = ["07777777777","07777777778"],
Content = "My super awesome message",
Schedule = "",
Tag = "Campaign1"
);
try
{
BatchMessageResponse result = apiInstance.SendBatch(smsMessage);
Debug.WriteLine(result);
}
catch (Exception e)
{
Debug.Print("Exception when calling BatchMessagesApi.SendBatch: " + e.Message );
}
}
}
}
/* Requires SMS Works Java SDK */
// Import classes:
//import io.swagger.client.ApiClient;
//import io.swagger.client.ApiException;
//import io.swagger.client.Configuration;
//import io.swagger.client.auth.*;
//import io.swagger.client.api.BatchMessagesApi;
import java.util.Date;
import java.text.SimpleDateFormat;
ApiClient defaultClient = Configuration.getDefaultApiClient();
// Configure API key authorization: JWT
ApiKeyAuth JWT = (ApiKeyAuth) defaultClient.getAuthentication("JWT");
JWT.setApiKey("YOUR API KEY");
BatchMessagesApi apiInstance = new BatchMessagesApi();
BatchMessage smsMessage = new BatchMessage(); // BatchMessage | Message properties
String[] destinationArray = { "07777777777", "07777777778", "07777777779" };
List fixedList = Arrays.asList( destinationArray );
List stringList = new ArrayList( fixedList );
setSender.setSender("AcmeCorp");
smsMessage.setDestinations(stringList);
smsMessage.setContent("My super awesome message");
smsMessage.setSchedule("");
smsMessage.setTag("AcmeCampaign1");
try {
BatchMessageResponse result = apiInstance.sendBatch(smsMessage);
System.out.println(result);
} catch (ApiException e) {
System.err.println("Exception when calling BatchMessagesApi#sendBatch");
e.printStackTrace();
}
var TheSmsWorksApi = require('the_sms_works_api');
var defaultClient = TheSmsWorksApi.ApiClient.instance;
// Configure API key authorization: JWT
var JWT = defaultClient.authentications['JWT'];
JWT.apiKey = 'YOUR API KEY';
var apiInstance = new TheSmsWorksApi.BatchMessagesApi();
var smsMessage = new TheSmsWorksApi.BatchMessage(); // BatchMessage | Message properties
smsMessage.sender = 'AcmeCorp';
smsMessage.destination = 07777777777;
smsMessage.content = 'My super awesome batch message';
smsMessage.schedule = '';
smsMessage.tag = 'Wedding';
var callback = function(error, data, response) {
if (error) {
console.error(error);
} else {
console.log('API called successfully. Returned data: ' + data);
}
};
apiInstance.sendBatch(smsMessage, callback);
<?php
require_once(__DIR__ . '/vendor/autoload.php');
// Configure API key authorization: JWT
Swagger\Client\Configuration::getDefaultConfiguration()->setApiKey('Authorization', 'YOUR_API_KEY');
$api_instance = new Swagger\Client\Api\BatchMessagesApi();
$sms_message = new \Swagger\Client\Model\BatchMessage(); // \Swagger\Client\Model\BatchMessage | Message properties
try {
$result = $api_instance->sendBatch($sms_message);
print_r($result);
} catch (Exception $e) {
echo 'Exception when calling BatchMessagesApi->sendBatch: ', $e->getMessage(), PHP_EOL;
}
?>
from __future__ import print_function
import time
import swagger_client
from swagger_client.rest import ApiException
from pprint import pprint
# Configure API key authorization: JWT
swagger_client.configuration.api_key['Authorization'] = 'YOUR_API_KEY'
# create an instance of the API class
api_instance = swagger_client.BatchMessagesApi()
sms_message = swagger_client.BatchMessage() # BatchMessage | Message properties
recipients = []
recipients.append("07777777777")
recipients.append("07777777778")
recipients.append("07777777779")
sms_message.sender = "AcmeCorp"
sms_message.destinations = recipients
sms_message.content = "My super awesome message"
sms_message.schedule = ""
sms_message.tag = "AcmeCampaign1"
try:
api_response = api_instance.send_batch(sms_message)
pprint(api_response)
except ApiException as e:
print("Exception when calling BatchMessagesApi->send_batch: %s\n" % e)
# load the gem
require 'swagger_client'
# setup authorization
SwaggerClient.configure do |config|
# Configure API key authorization: JWT
config.api_key['Authorization'] = 'YOUR API KEY'
end
api_instance = SwaggerClient::BatchMessagesApi.new
sms_message = SwaggerClient::BatchMessage.new # BatchMessage | Message properties
smsMessage.sender = "AcmePizza"
smsMessage.destination = "07777777777"
smsMessage.content = "My super awesome message"
smsMessage.schedule = ""
smsMessage.tag = "Campaign1"
begin
result = api_instance.send_batch(sms_message)
p result
rescue SwaggerClient::ApiError => e
puts "Exception when calling BatchMessagesApi->send_batch: #{e}"
end
GET /batch/{batchid}
Retrieve all messages in a batch with the given batch ID
// Requires SMS Works C# SDK
using System;
using System.Diagnostics;
using IO.Swagger.Api;
using IO.Swagger.Client;
using IO.Swagger.Model;
namespace Example
{
public class GetBatchByIdExample
{
public void main()
{
// Configure API key authorization: JWT
Configuration.Default.ApiKey.Add("Authorization", "YOUR_API_KEY");
var apiInstance = new BatchMessagesApi();
var batchid = batchid_example; // string | The ID of the batch you would like returned
try
{
MessagesResponse result = apiInstance.GetBatchById(batchid);
Debug.WriteLine(result);
}
catch (Exception e)
{
Debug.Print("Exception when calling BatchMessagesApi.GetBatchById: " + e.Message );
}
}
}
}
/* Requires SMS Works Java SDK */
// Import classes:
//import io.swagger.client.ApiClient;
//import io.swagger.client.ApiException;
//import io.swagger.client.Configuration;
//import io.swagger.client.auth.*;
//import io.swagger.client.api.BatchMessagesApi;
ApiClient defaultClient = Configuration.getDefaultApiClient();
// Configure API key authorization: JWT
ApiKeyAuth JWT = (ApiKeyAuth) defaultClient.getAuthentication("JWT");
JWT.setApiKey("YOUR API KEY");
BatchMessagesApi apiInstance = new BatchMessagesApi();
String batchid = "batchid_example"; // String | The ID of the batch you would like returned
try {
MessagesResponse result = apiInstance.getBatchById(batchid);
System.out.println(result);
} catch (ApiException e) {
System.err.println("Exception when calling BatchMessagesApi#getBatchById");
e.printStackTrace();
}
var TheSmsWorksApi = require('the_sms_works_api');
var defaultClient = TheSmsWorksApi.ApiClient.instance;
// Configure API key authorization: JWT
var JWT = defaultClient.authentications['JWT'];
JWT.apiKey = 'YOUR API KEY';
var apiInstance = new TheSmsWorksApi.BatchMessagesApi();
var batchid = "batchid_example"; // String | The ID of the batch you would like returned
var callback = function(error, data, response) {
if (error) {
console.error(error);
} else {
console.log('API called successfully. Returned data: ' + data);
}
};
apiInstance.getBatchById(batchid, callback);
<?php
require_once(__DIR__ . '/vendor/autoload.php');
// Configure API key authorization: JWT
Swagger\Client\Configuration::getDefaultConfiguration()->setApiKey('Authorization', 'YOUR_API_KEY');
$api_instance = new Swagger\Client\Api\BatchMessagesApi();
$sms_message = new \Swagger\Client\Model\BatchMessage(); // \Swagger\Client\Model\BatchMessage | Message properties
$api_instance = new Swagger\Client\Api\BatchMessagesApi();
$batchid = "batchid_example"; // string | The ID of the batch you would like returned
try {
$result = $api_instance->getBatchById($batchid);
print_r($result);
} catch (Exception $e) {
echo 'Exception when calling BatchMessagesApi->getBatchById: ', $e->getMessage(), PHP_EOL;
}
?>
from __future__ import print_function
import time
import swagger_client
from swagger_client.rest import ApiException
from pprint import pprint
# Configure API key authorization: JWT
swagger_client.configuration.api_key['Authorization'] = 'YOUR_API_KEY'
# create an instance of the API class
api_instance = swagger_client.BatchMessagesApi()
batchid = 'batchid_example' # str | The ID of the batch you would like returned
try:
api_response = api_instance.get_batch_by_id(batchid)
pprint(api_response)
except ApiException as e:
print("Exception when calling BatchMessagesApi->get_batch_by_id: %s\n" % e)
# load the gem
require 'swagger_client'
# setup authorization
SwaggerClient.configure do |config|
# Configure API key authorization: JWT
config.api_key['Authorization'] = 'YOUR API KEY'
end
api_instance = SwaggerClient::BatchMessagesApi.new
batchid = "batchid_example" # String | The ID of the batch you would like returned
begin
result = api_instance.get_batch_by_id(batchid)
p result
rescue SwaggerClient::ApiError => e
puts "Exception when calling BatchMessagesApi->get_batch_by_id: #{e}"
end
POST /batch/schedule
Schedules a batch of SMS messages to be sent at the date and time you specify
// Requires SMS Works C# SDK
using System;
using System.Diagnostics;
using IO.Swagger.Api;
using IO.Swagger.Client;
using IO.Swagger.Model;
namespace Example
{
public class ScheduleBatchExample
{
public void main()
{
// Configure API key authorization: JWT
Configuration.Default.ApiKey.Add("Authorization", "YOUR_API_KEY");
var apiInstance = new BatchMessagesApi();
var smsMessage = new BatchMessage( // BatchMessage | Message properties
Sender = "AcmePizza",
Destinations = ["07777777777","07777777778"],
Content = "My super awesome message",
Schedule = DateTimeOffset.Now.ToString("o"),
Tag = "Campaign1"
);
try
{
ScheduledBatchResponse result = apiInstance.ScheduleBatch(smsMessage);
Debug.WriteLine(result);
}
catch (Exception e)
{
Debug.Print("Exception when calling BatchMessagesApi.ScheduleBatch: " + e.Message );
}
}
}
}
/* Requires SMS Works Java SDK */
// Import classes:
//import io.swagger.client.ApiClient;
//import io.swagger.client.ApiException;
//import io.swagger.client.Configuration;
//import io.swagger.client.auth.*;
//import io.swagger.client.api.BatchMessagesApi;
import java.util.Date;
import java.text.SimpleDateFormat;
ApiClient defaultClient = Configuration.getDefaultApiClient();
// Configure API key authorization: JWT
ApiKeyAuth JWT = (ApiKeyAuth) defaultClient.getAuthentication("JWT");
JWT.setApiKey("YOUR API KEY");
BatchMessagesApi apiInstance = new BatchMessagesApi();
BatchMessage smsMessage = new BatchMessage(); // BatchMessage | Message properties
BatchMessagesApi apiInstance = new BatchMessagesApi();
BatchMessage smsMessage = new BatchMessage(); // BatchMessage | Message properties
String[] destinationArray = { "07777777777", "07777777778", "07777777779" };
List fixedList = Arrays.asList( destinationArray );
List stringList = new ArrayList( fixedList );
setSender.setSender("AcmeCorp");
smsMessage.setDestinations(stringList);
smsMessage.setContent("My super awesome message");
smsMessage.setSchedule(new SimpleDateFormat("EEE MMM dd hh:mm:ss yyyy").format(new Date()));
smsMessage.setTag("AcmeCampaign1");
try {
ScheduledBatchResponse result = apiInstance.scheduleBatch(smsMessage);
System.out.println(result);
} catch (ApiException e) {
System.err.println("Exception when calling BatchMessagesApi#scheduleBatch");
e.printStackTrace();
}
var TheSmsWorksApi = require('the_sms_works_api');
var defaultClient = TheSmsWorksApi.ApiClient.instance;
// Configure API key authorization: JWT
var JWT = defaultClient.authentications['JWT'];
JWT.apiKey = 'YOUR API KEY';
var apiInstance = new TheSmsWorksApi.BatchMessagesApi();
var smsMessage = new TheSmsWorksApi.BatchMessage(); // BatchMessage | Message properties
smsMessage.sender = 'AcmeCorp';
smsMessage.destination = 07777777777;
smsMessage.content = 'My super awesome scheduled batch message';
smsMessage.schedule = new Date('16 October 2016 17:00:00');
smsMessage.tag = 'Marriage';
var callback = function(error, data, response) {
if (error) {
console.error(error);
} else {
console.log('API called successfully. Returned data: ' + data);
}
};
apiInstance.scheduleBatch(smsMessage, callback);
<?php
require_once(__DIR__ . '/vendor/autoload.php');
// Configure API key authorization: JWT
Swagger\Client\Configuration::getDefaultConfiguration()->setApiKey('Authorization', 'YOUR_API_KEY');
$api_instance = new Swagger\Client\Api\BatchMessagesApi();
$sms_message = new \Swagger\Client\Model\BatchMessage(); // \Swagger\Client\Model\BatchMessage | Message properties
try {
$result = $api_instance->scheduleBatch($sms_message);
print_r($result);
} catch (Exception $e) {
echo 'Exception when calling BatchMessagesApi->scheduleBatch: ', $e->getMessage(), PHP_EOL;
}
?>
from __future__ import print_function
import time
import swagger_client
from swagger_client.rest import ApiException
from pprint import pprint
# Configure API key authorization: JWT
swagger_client.configuration.api_key['Authorization'] = 'YOUR_API_KEY'
# create an instance of the API class
api_instance = swagger_client.BatchMessagesApi()
sms_message = swagger_client.BatchMessage() # BatchMessage | Message properties
recipients = []
recipients.append("07777777777")
recipients.append("07777777778")
recipients.append("07777777779")
d = datetime.now(timezone.utc)
sms_message.sender = "AcmeCorp"
sms_message.destinations = recipients
sms_message.content = "My super awesome message"
sms_message.schedule = d.strftime('%a %d %b %Y %H:%M:%S %Z')
sms_message.tag = "AcmeCampaign1"
try:
api_response = api_instance.schedule_batch(sms_message)
pprint(api_response)
except ApiException as e:
print("Exception when calling BatchMessagesApi->schedule_batch: %s\n" % e)
# load the gem
require 'swagger_client'
# setup authorization
SwaggerClient.configure do |config|
# Configure API key authorization: JWT
config.api_key['Authorization'] = 'YOUR API KEY'
end
api_instance = SwaggerClient::BatchMessagesApi.new
sms_message = SwaggerClient::BatchMessage.new # BatchMessage | Message properties
smsMessage.sender = "AcmePizza"
smsMessage.destination = "07777777777"
smsMessage.content = "My super awesome message"
smsMessage.schedule = Time.now.utc.iso8601
smsMessage.tag = "Campaign1"
begin
result = api_instance.schedule_batch(sms_message)
p result
rescue SwaggerClient::ApiError => e
puts "Exception when calling BatchMessagesApi->schedule_batch: #{e}"
end
DELETE /batches/schedule/{batchid}
Cancels a scheduled SMS message batch
// Requires SMS Works C# SDK
using System;
using System.Diagnostics;
using IO.Swagger.Api;
using IO.Swagger.Client;
using IO.Swagger.Model;
namespace Example
{
public class CancelScheduledBatchJobExample
{
public void main()
{
// Configure API key authorization: JWT
Configuration.Default.ApiKey.Add("Authorization", "YOUR_API_KEY");
var apiInstance = new BatchMessagesApi();
var batchid = batchid_example; // string | The ID of the batch you would like returned
try
{
CancelledMessageResponse result = apiInstance.CancelScheduledBatchJob(batchid);
Debug.WriteLine(result);
}
catch (Exception e)
{
Debug.Print("Exception when calling BatchMessagesApi.CancelScheduledBatchJob: " + e.Message );
}
}
}
}
/* Requires SMS Works Java SDK */
// Import classes:
//import io.swagger.client.ApiClient;
//import io.swagger.client.ApiException;
//import io.swagger.client.Configuration;
//import io.swagger.client.auth.*;
//import io.swagger.client.api.BatchMessagesApi;
ApiClient defaultClient = Configuration.getDefaultApiClient();
// Configure API key authorization: JWT
ApiKeyAuth JWT = (ApiKeyAuth) defaultClient.getAuthentication("JWT");
JWT.setApiKey("YOUR API KEY");
BatchMessagesApi apiInstance = new BatchMessagesApi();
String batchid = "batchid_example"; // String | The ID of the batch you would like cancelled
try {
CancelledMessageResponse result = apiInstance.cancelScheduledBatchJob(batchid);
System.out.println(result);
} catch (ApiException e) {
System.err.println("Exception when calling BatchMessagesApi#cancelScheduledBatchJob");
e.printStackTrace();
}
var TheSmsWorksApi = require('the_sms_works_api');
var defaultClient = TheSmsWorksApi.ApiClient.instance;
// Configure API key authorization: JWT
var JWT = defaultClient.authentications['JWT'];
JWT.apiKey = 'YOUR API KEY';
var apiInstance = new TheSmsWorksApi.BatchMessagesApi();
var batchid = "batchid_example"; // String | The ID of the batch you would like returned
var callback = function(error, data, response) {
if (error) {
console.error(error);
} else {
console.log('API called successfully. Returned data: ' + data);
}
};
apiInstance.cancelScheduledBatchJob(batchid, callback);
<?php
require_once(__DIR__ . '/vendor/autoload.php');
// Configure API key authorization: JWT
Swagger\Client\Configuration::getDefaultConfiguration()->setApiKey('Authorization', 'YOUR_API_KEY');
$api_instance = new Swagger\Client\Api\BatchMessagesApi();
$batchid = "batchid_example"; // string | The ID of the batch you would like returned
try {
$result = $api_instance->cancelScheduledBatchJob($batchid);
print_r($result);
} catch (Exception $e) {
echo 'Exception when calling BatchMessagesApi->cancelScheduledBatchJob: ', $e->getMessage(), PHP_EOL;
}
?>
from __future__ import print_function
import time
import swagger_client
from swagger_client.rest import ApiException
from pprint import pprint
# Configure API key authorization: JWT
swagger_client.configuration.api_key['Authorization'] = 'YOUR_API_KEY'
# create an instance of the API class
api_instance = swagger_client.BatchMessagesApi()
batchid = 'batchid_example' # str | The ID of the batch you would like returned
try:
api_response = api_instance.cancel_scheduled_batch_job(batchid)
pprint(api_response)
except ApiException as e:
print("Exception when calling BatchMessagesApi->cancel_scheduled_batch_job: %s\n" % e)
# load the gem
require 'swagger_client'
# setup authorization
SwaggerClient.configure do |config|
# Configure API key authorization: JWT
config.api_key['Authorization'] = 'YOUR API KEY'
end
api_instance = SwaggerClient::BatchMessagesApi.new
batchid = "batchid_example" # String | The ID of the batch you would like returned
begin
result = api_instance.cancel_scheduled_batch_job(batchid)
p result
rescue SwaggerClient::ApiError => e
puts "Exception when calling BatchMessagesApi->cancel_scheduled_batch_job: #{e}"
end
Delivery Reports
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.
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.
Delivery reports are JSON objects, with a format as follows:
{
"__v": 0,
"_id": "5ab817e969722262a9711bb4",
"content": "Greetings!",
"created": "2017-03-25T21:43:05.667Z",
"credits": 1,
"customerid": "your customer id",
"destination": 447777777777,
"failurereason" : {
"code" : 1,
"details" : "Handset Error: Number does not exist or has not been assigned to a user.",
"permanent" : false
},
"international": false,
"keyword": "",
"messageid": "128032521395903584",
"modified": "2017-03-25T21:43:13.229Z",
"schedule": "2017-03-25T21:43:05.665Z",
"sender": "TheSMSWorks",
"status": "DELIVERED",
"tag": ""
}
Incoming SMS messages (see below), sent to Keywords or Longcodes that you have purchased, all require their own delivery report end-point URL, allowing you to write explicit code for each one.
Credit charges
We assume that any message sent will be delivered. If it is not delivered for a defined reason we will put the relevant number of credits back onto your account.
More detailed help with understanding delivery reports can be found on our SMS Delivery Report Overview page.
We are unable to refund credits when the mobile networks respond with a delivery status of "UNKNOWN".
We cannot refund undelivered messages to numbers sent outside the UK for the simple reason that we are charged for all international texts, regardless of the outcome.
| Status | Notes |
|---|---|
| DELIVERED | Mobile number is correct; message has been successfully delivered to the handset. |
| ACCEPTED | The SMS Works platform has accepted the message but no delivery report has yet been received from the networks. |
| FAILED | The message could not be sent. The reason will be recorded on the delivery report. The FAILED status is only used for batch messages, where we need to record sending failures. For non-batch messages, any failure will be recorded in the API response. |
| UNDELIVERED | The message could not be delivered. The text credit is added back to your account. (Except text sent outside the UK.) |
| EXPIRED | The message was not delivered within the validity period of the relevant mobile phone network. Networks will try to deliver a message for up to 72 hours, then the message will expire (Different networks have different validity periods). The credit for the message will be refunded. |
| REJECTED | The message was rejected by The SMS Works Platform. No credit will be deducted. |
You can set a low credit warning level on your account page. We will send you an email, once every 24 hours, if your credit balance drops below the warning level that you've set. (Set this to 0 if you do not wish to receive a low credit warning.)
We charge 1 credit for a standard message of up to 160 characters. Messages can be up to a maximum of 1280 characters in length.
Messages longer than 160 characters get segmented into chunks of 153 characters to send to the recipient's handset, so you'll be charged 1 credit per 153 characters. For example, a message of 161 characters will be sent as two messages - one of 153 characters and one of 8 - at a cost of 2 credits. Happily, most modern handsets will stitch these back together and present them as a single message.
International messages (sent to numbers outside the UK) are typically charged double, but for certain countries may be charged fractions of credits (e.g. 2.5). Please contact us for rates for each country.
Incoming SMS
You can receive incoming SMS messages as well as sending them with The SMS Works.
We offer both keywords on a short code as well as virtual mobile numbers that can be associated with your account.
Incoming messages are forwarded to a URL you specify via HTTP POST, as JSON objects, with a format as shown below. The 'parts' parameter indicates how many parts the message was received in. Each part corresponds to 1 text message length (160 characters).
{
"content": "INCOMING CONTENT",
"from": "447777777777",
"messageid": "6170167",
"messagetype": "incoming",
"to": "447777777778",
"parts": 1
}
SDKs
To expedite integration, we've built SDK wrappers for our API, available in Java, Ruby, C#, Javascript (Node.js), PHP & Python. Clone them from GitHub to get started straightaway.
Error codes
Errors listed as 'permanent' indicate that the submitted message will not be delivered. For messages resulting in errors that are not 'permanent', we will automatically try to deliver the message again, up until the default timeout, which is 48 hours. Delivery reports will record and be updated with the applicable message status, and will record any error codes and messages.
Bad Message Content Errors (http 400) |
|||
|---|---|---|---|
Code |
Permanent |
Message |
Notes |
4001 |
true |
Message length is 0 characters. Cannot send message. Please check and try again. | |
4002 |
true |
Cannot send messages longer than 1280 characters. | You can send messages up to 1280 characters in length. |
4003 |
true |
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 |
true |
Invalid destination number. | We were not able to determine a valid UK or international destination number. |
4005 |
true |
Tag longer than 280 characters. | The maximum length of a tag is 280 characters, including spaces. |
4006 |
true |
Message contains profanity. | Profane language has been detected in the content of the message. Message not sent. |
4007 |
true |
Message contains blocked terms. Account disabled. | The message contains terms that match our phishing filters. Your account has been disabled as a precaution. |
4008 |
true |
Invalid message ID. | Returned when an invalid message ID is supplied to the /message/{:messageid} method. |
4009 |
true |
Invalid date/time supplied: [date/time] | Returned by the message scheduler if an invalid date, or a date in past is supplied. |
Authentication Errors (http 401) |
|||
Code |
Permanent |
Message |
Notes |
4011 |
true |
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 |
Permanent |
Message |
Notes |
4021 |
true |
Insufficient credit to send message. | Please add more credits to your account in order to continue sending messages. |
Authorisation Errors (http 403) |
|||
Code |
Permanent |
Message |
Notes |
4031 |
true |
Not authorised. | |
4032 |
true |
Account not found. | |
4033 |
true |
Account disabled. | |
4034 |
true |
This account is not enabled for international SMS. Cannot send message. | |
Service Errors (http 503) |
|||
Code |
Permanent |
Message |
Notes |
5001 |
true |
Handset Error: Number does not exist or has not been assigned to a user. | |
5002 |
true |
Service database error. | |
5004 |
true |
Message has been sent to the operator, whereas the request was rejected, or a delivery report with status REJECTED was reverted | |
5006 |
false |
Handset Error: No response. Handset may be switched off or in a low signal area. | |
5008 |
false |
Handset Error: Roaming not allowed. | |
5009 |
true |
Message has been sent to the operator, but has failed to deliver, since a delivery report with status UNDELIVERED was reverted from the operator. | |
5010 |
true |
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. | |
5011 |
true |
The subscriber’s mobile service has been suspended by the operator. | |
5013 |
false |
Handset Error: Device is set to Do Not Disturb. | |
5015 |
false |
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. | |
5034 |
false |
Handset Error: System failure. | |
We think we've got everything covered, but if not please do contact us.