//
SMS API developer zone

The SMS Works Developer Zone

Integrate SMS into your app, software or website in minutes

 Get a Free Account
 API Reference
 Download SDKs
 

Quick Start

There are just a few simple steps to integrate The SMS Works service into your application, software or website.

  1. Open a free account with 50 free SMS credits pre-loaded
  2. Set up authentication
  3. Use our simple methods to send and receive messages: There are 3 options.
    1. Choose from our SDKs
    2. Achieve a simple integration with cURL using our code snippets
    3. Make regular HTTP POST and GET calls to our SMS API end-points

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.

Use our free unicode detector tool to help identify and eliminate any unicode characters in you texts.

 

Authentication

Set up

The SMS Works uses JSON Web Tokens (JWT) for authentication. Follow these steps to set up authentication:

  1. Set up a free account. Your account comes with 50 free messages. Let us know if you need more.
  2. From your account page, generate an API Key & Secret from the ' API Key' tab.
  3. Take the API Key & Secret, along with your Customer ID. (Your Customer ID is on your account page and will appear after you have pressed the 'New Key/Secret button). Then 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.
    postman token request
  4. 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.

 

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.

Read more about SMS sender IDs,

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 often costs more. Please see out international SMS pricing table.

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.

Use our free SMS message length calculator to check message length and number of SMS credits required to send the message.

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 Sun Sep 03 2017 15:34:23 GMT+0100 (BST)

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 developers choose to place their request in a code loop for testing. Please be very careful that all or your 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.

 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.

 Things to check before your SMS integration goes live

Before your SMS integration goes live, please check the following important things:

  1. Check your messages use the GSM character set to avoid using more credits than expected. Free unicode detector.
  2. Triple-check your code in all possible scenarios
  3. Check the SMS message length is as intended
  4. Set up low credits warning email alerts in your account
  5. White list our domains so that alerts and other emails can reach you: @thesmswork.co.uk, @thesmswork.co.uk
  6. If you have a reply number, make sure that replies are being handled correctly
  7.  A reminder that failed international texts are not refunded.
Please read this important article. it highlights some of the more common things that are easily overlooked.
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

    API Reference

 

Sends an SMS Message


	curl --location --request POST 'https://api.thesmsworks.co.uk/v1/message/send' --header 'Authorization: YOUR JWT GOES HERE' --header 'Content-Type: application/json' --header 'Content-Type: text/plain' --data-raw '{
			"sender": "",
			"destination": "",
			"content": "",
			"tag": ""
	}'
  Copy 

  // 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 );
              }
          }
      }
  }
  Copy 

    /* 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();
    }
  Copy 

	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);
  Copy 

<!?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 (\Swagger\Client\ApiException $e) {
      echo 'Exception when calling MessagesApi->sendMessage: ', $e->getMessage(), PHP_EOL;
  }
?>
  Copy 

    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
    configuration = swagger_client.Configuration()
    configuration.api_key['Authorization'] = 'YOUR_API_KEY'

    # create an instance of the API class
    api_instance = swagger_client.MessagesApi()

    sender = 'AcmeCorp'
    destination = '07777777777'
    content = 'Your message'
    sms_message = swagger_client.Message(sender=sender, destination=destination, content=content)

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

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

POST /message/schedule

    API Reference

 

Schedules an SMS message to be sent at the date-time you specify


curl --location --request POST 'https://api.thesmsworks.co.uk/v1/message/schedule' --header 'Authorization: YOUR JWT GOES HERE' --header 'Content-Type: application/json' --header 'Content-Type: text/plain' --data-raw '{
    "sender": "",
    "destination": "",
    "content": "",
    "schedule": "",
    "tag": ""
}'
  Copy 

  // 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 );
              }
          }
      }
  }
  Copy 

    /* 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();
    }
  Copy 

	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);
  Copy 

    <?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 (\Swagger\Client\ApiException $e) {
        echo 'Exception when calling MessagesApi->scheduleMessage: ', $e->getMessage(), PHP_EOL;
    }
    ?>
  Copy 

    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
    configuration = swagger_client.Configuration()
    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)
  Copy 

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

POST /messages

    API Reference

 

Get messages matching your search criteria


curl --location --request POST 'https://api.thesmsworks.co.uk/v1/messages' --header 'Authorization: YOUR JWT GOES HERE' --header 'Content-Type: application/json' --header 'Content-Type: text/plain' --data-raw '{
    "status": "",
    "destination": "",
    "sender": "",
    "keyword": "",
    "from": "",
    "to": ""
}'
  Copy 

  // 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 );
              }
          }
      }
  }
  Copy 

    /* 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();
    }
  Copy 

	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);
  Copy 

    <?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 (\Swagger\Client\ApiException $e) {
        echo 'Exception when calling MessagesApi->getMessages: ', $e->getMessage(), PHP_EOL;
    }
    ?>
  Copy 

    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
    configuration = swagger_client.Configuration()
    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)
  Copy 

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

GET /messages/{messageid}

    API Reference

 

Retrieve a delivery report for the given message ID


curl --location --request GET 'https://api.thesmsworks.co.uk/v1/messages/' --header 'Authorization: YOUR JWT GOES HERE'
  Copy 

  // 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 );
              }
          }
      }
  }
  Copy 

    /* 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();
    }
  Copy 

	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);
  Copy 

    <?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 (\Swagger\Client\ApiException $e) {
        echo 'Exception when calling MessagesApi->getMessageById: ', $e->getMessage(), PHP_EOL;
    }
    ?>
  Copy 

    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
    configuration = swagger_client.Configuration()
    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)
  Copy 

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

DELETE /messages/schedule/{messageid}

    API Reference

 

Cancels a scheduled SMS message


curl --location --request DELETE 'https://api.thesmsworks.co.uk/v1/messages/schedule/SCHEDULEDMESSAGEID' --header 'Authorization: YOUR JWT GOES HERE'
  Copy 

  // 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 );
              }
          }
      }
  }
  Copy 

    /* 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();
    }
  Copy 

	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);
  Copy 

    <?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 (\Swagger\Client\ApiException $e) {
        echo 'Exception when calling MessagesApi->cancelScheduledJob: ', $e->getMessage(), PHP_EOL;
    }
    ?>
  Copy 

    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
    configuration = swagger_client.Configuration()
    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)
  Copy 

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

POST /batch/send

    API Reference

 

Send a single SMS message to multiple recipients. Sending to multiple numbers is limited to 500 recipients.


curl --location --request POST 'https://api.thesmsworks.co.uk/v1/batch/send' --header 'Authorization: YOUR JWT GOES HERE' --header 'Content-Type: application/json' --header 'Content-Type: text/plain' --data-raw '{
    "sender": "",
    "destinations": [
        "",
        ""
    ],
    "content": "",
    "tag": ""
}'
  Copy 

  // 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 );
              }
          }
      }
  }
  Copy 

    /* 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();
    }
  Copy 

	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);
  Copy 

    <?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 (\Swagger\Client\ApiException $e) {
        echo 'Exception when calling BatchMessagesApi->sendBatch: ', $e->getMessage(), PHP_EOL;
    }
    ?>
  Copy 

    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
    configuration = swagger_client.Configuration()
    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)
  Copy 

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

GET /batch/{batchid}

    API Reference

 

Retrieve all messages in a batch with the given batch ID


curl --location --request GET 'https://api.thesmsworks.co.uk/v1/batch/' --header 'Authorization: YOUR JWT GOES HERE'
  Copy 

  // 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 );
              }
          }
      }
  }
  Copy 

    /* 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();
    }
  Copy 

	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);
  Copy 

    <?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 (\Swagger\Client\ApiException $e) {
        echo 'Exception when calling BatchMessagesApi->getBatchById: ', $e->getMessage(), PHP_EOL;
    }
    ?>
  Copy 

    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
    configuration = swagger_client.Configuration()
    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)
  Copy 

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

POST /batch/schedule

    API Reference

 

Schedules a batch of SMS messages to be sent at the date and time you specify


curl --location --request POST 'https://api.thesmsworks.co.uk/v1/batch/schedule' --header 'Authorization: YOUR JWT GOES HERE' --header 'Content-Type: application/json' --header 'Content-Type: text/plain' --data-raw '{
    "sender": "",
    "destinations": [
        "",
        ""
    ],
    "content": "",
    "schedule": "",
    "tag": ""
}'
  Copy 

  // 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 );
              }
          }
      }
  }
  Copy 

    /* 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();
    }
  Copy 

	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);
  Copy 

    <?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 (\Swagger\Client\ApiException $e) {
        echo 'Exception when calling BatchMessagesApi->scheduleBatch: ', $e->getMessage(), PHP_EOL;
    }
    ?>
  Copy 

    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
    configuration = swagger_client.Configuration()
    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)
  Copy 

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

DELETE /batches/schedule/{batchid}

    API Reference

 

Cancels a scheduled SMS message batch


curl --location --request DELETE 'https://api.thesmsworks.co.uk/v1/batches/schedule/MESSAGEID' --header 'Authorization: YOUR JWT GOES HERE'
  Copy 

  // 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 );
              }
          }
      }
  }
  Copy 

    /* 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();
    }
  Copy 

	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);
  Copy 

    <?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 (\Swagger\Client\ApiException $e) {
        echo 'Exception when calling BatchMessagesApi->cancelScheduledBatchJob: ', $e->getMessage(), PHP_EOL;
    }
    ?>
  Copy 

    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
    configuration = swagger_client.Configuration()
    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)
  Copy 

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

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.

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.

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.
You can also read more about the main reasons why a text messge might fail.

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

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.  

5020

true

 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.  

5034

false

 Handset Error: System failure.  
 We think we've got everything covered, but if not please do contact us.