NAV Navbar
cURL javascript

Introduction

Welcome to the FastSMS REST API!

Using our application protocol interface (API) developers can integrate all fastsms features into any project. Using this REST API, you can send and receive SMS messages, track the delivery of sent messages, and retrieve and modify message history.

We’ll provide you our API documentation even before you sign up for your free account.

We have language bindings (PHP, .NET, C#, Java, Python, Ruby etc) and new SDKs are being added to our documentation all the time. You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

API Key

Before you can start using our APIs, you need an API key. It’s easy.

If you don't have an account, you can sign up for free one.

Sign in your account and access your account seetings in top right.

Settings

In the account settings screen, choose API Config tab.

Api key

In our examples the key used will be sometestapikey.

If you think your API Key is compromised, you can generate a new key that overrides the previous one.

Authentication

To authorize, use this code:

# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
  -H "Authorization: sometestapikey"
const Http = new XMLHttpRequest();

const url = 'api_endpoint_here';
Http.open("GET", url);

// You can just pass the correct header with each request
Http.setRequestHeader('Authorization','sometestapikey');

// ...
// process XMLHttpRequest response
// ...

Make sure to replace sometestapikey with your API key.

FastSMS API expects for the API Key to be included in all API requests to the server in a header that looks like the following:

Authorization: sometestapikey

Unauthenticated requests will return an HTTP 403 response. The API token is your key to accessing all of your resources via FastSMS API. Keep it safe. SSL must be used in all FastSMS API interactions.

API Hosts

Production: https://secureapi.fastsms.co.uk

Sandbox: https://sandboxsecureapi.fastsms.co.uk

Pagination

A ubiquitous method for handling large datasets and responses in the browser-based Web but developers of API-based apps also turn to pagination in order to minimize response times for requests and generally improve the end-user experience. Without pagination, a simple search could return millions or even billions of hits causing extraneous network traffic.

Parameters of pagination:

page (integer) - You can specify further pages with the ‘page’ parameter. Default value: 1

per_page (integer) - Requests will be paginated to 25 items by default, you can also set a custom page size up to 100 with the ‘per_page’ parameter. Default value : 25

sort (string) - Accommodate sorting requirements by letting the sort parameter take in list of comma separated fields, each with a possible unary negative to imply descending sort order.

Balance

Get Balance

curl -X GET "https://secureapi.fastsms.co.uk/balance"
  -H "Authorization: sometestapikey"
const Http = new XMLHttpRequest();

const url = 'https://secureapi.fastsms.co.uk/balance';
Http.open("GET", url);
Http.setRequestHeader('Authorization','sometestapikey');
Http.send();

Http.onreadystatechange = (e) => {
  console.log(Http.responseText)
}

The above command returns JSON structured like this:

{
  "balance": 10
}

This endpoint retrieves the balance currently available on your account.

HTTP Request

GET https://secureapi.fastsms.co.uk/balance

Responses

Code Description
200 Successful operation
403 Failed authentication or not authorised to access feature

Contact

Get Contact

curl -X GET "https://secureapi.fastsms.co.uk/contact"
  -H "Authorization: sometestapikey"
const Http = new XMLHttpRequest();

const url = 'https://secureapi.fastsms.co.uk/contact';
Http.open("GET", url);
Http.setRequestHeader('Authorization','sometestapikey');
Http.send();

Http.onreadystatechange = (e) => {
  console.log(Http.responseText)
}

The above command returns JSON structured like this:

[
  {
    "id": 1,
    "number": "0690001122",
    "firstName": "John",
    "surname": "Moore",
    "company": "Commify",
    "email": "john.moore@commify.com",
    "city": "Paris",
    "country": "France",
    "custom1": "Any",
    "custom2": "Any",
    "custom3": "Any",
    "custom4": "Any",
    "custom5": "Any",
    "custom6": "Any",
    "custom7": "Any",
    "custom8": "Any",
    "custom9": "Any",
    "custom10": "Any",
    "stop": true
  }
]

This endpoint list all account contact entries.

HTTP Request

GET https://secureapi.fastsms.co.uk/contact

Parameters

page, per_page_, sort - Pagination

Responses

Code Description
200 Successful operation
401 Forbidden

Post Contact

curl -X POST "https://secureapi.fastsms.co.uk/contact"
-H "Authorization: sometestapikey"
-H "Content-Type: application/json"
-d "{ \"id\": 1, \"number\": \"0690001122\", \"firstName\": \"John\", \"surname\": \"Moore\", \"company\": \"Commify\",
\"email\": \"john.moore@commify.com\", \"city\": \"Paris\", \"country\": \"France\", \"custom1\": \"Any\", \"custom2\": \"Any\", \"custom3\": \"Any\", \"custom4\": \"Any\", \"custom5\": \"Any\", \"custom6\": \"Any\", \"custom7\": \"Any\", \"custom8\": \"Any\", \"custom9\": \"Any\", \"custom10\": \"Any\", \"stop\": true }"

const Http = new XMLHttpRequest();

const url = 'https://secureapi.fastsms.co.uk/contact';
Http.open("POST", url);
Http.setRequestHeader("Content-Type", "application/json;charset=UTF-8");
Http.send(JSON.stringify({ "id": 1, "number": "0690001122", "firstName": "John", "surname": "Moore", "company": "Commify",
"email": "john.moore@commify.com", "city": "Paris", "country": "France", "custom1": "Any", "custom2": "Any", "custom3": "Any", "custom4": "Any", "custom5": "Any", "custom6": "Any", "custom7": "Any", "custom8": "Any", "custom9": "Any", "custom10": "Any", "stop": true } ));

Http.onreadystatechange = (e) => {
  console.log(Http.responseText)
}

The above command returns JSON structured like this:

{
  "id": 1,
  "number": "0690001122",
  "firstName": "John",
  "surname": "Moore",
  "company": "Commify",
  "email": "john.moore@commify.com",
  "city": "Paris",
  "country": "France",
  "custom1": "Any",
  "custom2": "Any",
  "custom3": "Any",
  "custom4": "Any",
  "custom5": "Any",
  "custom6": "Any",
  "custom7": "Any",
  "custom8": "Any",
  "custom9": "Any",
  "custom10": "Any",
  "stop": true
}

This endpoint create a contact resource.

HTTP Request

POST https://secureapi.fastsms.co.uk/contact

Parameters

Responses

Code Description
201 Successful operation
401 Forbidden
412 Duplicate entry

Get Contact by ID

curl -X GET "https://secureapi.fastsms.co.uk/contact/id"
  -H "Authorization: sometestapikey"
const Http = new XMLHttpRequest();

const url = 'https://secureapi.fastsms.co.uk/contact/id';
Http.open("GET", url);
Http.setRequestHeader('Authorization','sometestapikey');
Http.send();

Http.onreadystatechange = (e) => {
  console.log(Http.responseText)
}

The above command returns JSON structured like this:

{
  "id": 1,
  "number": "0690001122",
  "firstName": "John",
  "surname": "Moore",
  "company": "Commify",
  "email": "john.moore@commify.com",
  "city": "Paris",
  "country": "France",
  "custom1": "Any",
  "custom2": "Any",
  "custom3": "Any",
  "custom4": "Any",
  "custom5": "Any",
  "custom6": "Any",
  "custom7": "Any",
  "custom8": "Any",
  "custom9": "Any",
  "custom10": "Any",
  "stop": true
}

This endpoint find contact resource by ID.

HTTP Request

GET https://secureapi.fastsms.co.uk/contact/id

Parameters

Responses

Code Description
200 Successful operation
401 Forbidden
404 Resource not found

Delete Contact by ID

curl -X DELETE "https://secureapi.fastsms.co.uk/contact/id"
  -H "Authorization: sometestapikey"
const Http = new XMLHttpRequest();

const url = 'https://secureapi.fastsms.co.uk/contact/id';
Http.open("DELETE", url);
Http.setRequestHeader('Authorization','sometestapikey');
Http.send();

Http.onreadystatechange = (e) => {
  console.log(Http.responseText)
}

The above command returns JSON structured like this:

{}

This endpoint remove contact resource by ID.

HTTP Request

DELETE https://secureapi.fastsms.co.uk/contact/id

Parameters

Responses

Code Description
200 Successful operation
401 Forbidden

Patch Contact by ID

curl -X PATCH "https://secureapi.fastsms.co.uk/contact"
-H "Authorization: sometestapikey"
-H "Content-Type: application/json"
-d "{ \"id\": 1, \"number\": \"0690001122\", \"firstName\": \"John\", \"surname\": \"Moore\", \"company\": \"Esendex\",
\"email\": \"john.moore@esendex.com\", \"city\": \"Paris\", \"country\": \"France\", \"custom1\": \"Any\", \"custom2\": \"Any\", \"custom3\": \"Any\", \"custom4\": \"Any\", \"custom5\": \"Any\", \"custom6\": \"Any\", \"custom7\": \"Any\", \"custom8\": \"Any\", \"custom9\": \"Any\", \"custom10\": \"Any\", \"stop\": true }"

const Http = new XMLHttpRequest();

const url = 'https://secureapi.fastsms.co.uk/contact';
Http.open("PATCH", url);
Http.setRequestHeader("Content-Type", "application/json;charset=UTF-8");
Http.send(JSON.stringify({ "id": 1, "number": "0690001122", "firstName": "John", "surname": "Moore", "company": "Esendex",
"email": "john.moore@esendex.com", "city": "Paris", "country": "France", "custom1": "Any", "custom2": "Any", "custom3": "Any", "custom4": "Any", "custom5": "Any", "custom6": "Any", "custom7": "Any", "custom8": "Any", "custom9": "Any", "custom10": "Any", "stop": true } ));

Http.onreadystatechange = (e) => {
  console.log(Http.responseText)
}

The above command returns JSON structured like this:

{
  "id": 1,
  "number": "0690001122",
  "firstName": "John",
  "surname": "Moore",
  "company": "Esendex",
  "email": "john.moore@esendex.com",
  "city": "Paris",
  "country": "France",
  "custom1": "Any",
  "custom2": "Any",
  "custom3": "Any",
  "custom4": "Any",
  "custom5": "Any",
  "custom6": "Any",
  "custom7": "Any",
  "custom8": "Any",
  "custom9": "Any",
  "custom10": "Any",
  "stop": true
}

This endpoint update contact resource by ID.

HTTP Request

PATCH https://secureapi.fastsms.co.uk/contact/id

Parameters

Responses

Code Description
200 Successful operation
401 Forbidden
404 Resource not found
412 Duplicate entry

Campaign

Get Campaign

curl -X GET "https://secureapi.fastsms.co.uk/campaign?page=1&per_page=25"
  -H "Authorization: sometestapikey"
const Http = new XMLHttpRequest();

const url = 'https://secureapi.fastsms.co.uk/campaign?page=1&per_page=25';
Http.open("GET", url);
Http.setRequestHeader('Authorization','sometestapikey');
Http.send();

Http.onreadystatechange = (e) => {
  console.log(Http.responseText)
}

The above command returns JSON structured like this:

[
  {
    "id": 1,
    "name": "Campaign Name",
    "sendDate": "2019-05-07T10:31:36.642Z",
    "senderId": "AnySenderId",
    "message": "Any Message" ,
    "batchSize": 0,
    "batchIndex": 0,
    "smsCount": 0,
    "smsParts": 0,
    "beingProcessed": true,
    "custom": "Any Custom",
    "validity": 0,
    "sourceInterface": "Any Source",
    "parsedNumbers": {
      "valid": [
        "Any"
      ],
      "bad": [
        "Any"
      ],
      "duplicated": [
        "Any"
      ]
    }
  }
]

This endpoint list all schedule campaign entries.

HTTP Request

GET https://secureapi.fastsms.co.uk/campaign?page=1&per_page=25

Parameters

page, per_page_, sort - Pagination

since (string) - Get all campaigns created since the given date. The format is yyyy-MM-ddThh:mm:ssZ where y=year, M=month, d=day, T=separator, h=hour, m=min and s=seconds. The value is treated as per ISO 8601 semantics, e.g. without time zone information the value is assumed to be the local time of the server, otherwise as an offset from UTC with Z representing a UTC time.

Responses

Code Description
200 Successful operation
401 Forbidden

Post Campaign

curl -X POST "https://secureapi.fastsms.co.uk/campaign"
-H "Authorization: sometestapikey"
-H "Content-Type: application/json"
-d "{ \"from\": \"string\", \"message\": \"Any message text\", \"validity\": 48,
\"sendDate\": \"2019-05-07T10:59:05.552Z\", \"spread\": 0, \"characterSet\": \"string\",
\"name\": \"string\", \"custom\": \"Any custom\", \"numbers\": [ Any ], \"contacts\": [ 0 ],
\"groups\": [ 0 ] }"
const Http = new XMLHttpRequest();

const url = 'https://secureapi.fastsms.co.uk/campaign';
Http.open("POST", url);
Http.setRequestHeader("Content-Type", "application/json;charset=UTF-8");
Http.send(JSON.stringify({ "from": "string", "message": Any message text, "validity": 48,
"sendDate": "2019-05-07T10:59:05.552Z", "spread": 0, "characterSet": "string",
"name": "string", "custom": Any custom, "numbers": [ Any ], "contacts": [ 0 ],
"groups": [ 0 ] }));

Http.onreadystatechange = (e) => {
  console.log(Http.responseText)
}

The above command returns JSON structured like this:

{
  "id": 0,
  "name": "Any campaign name",
  "sendDate": "2019-05-07T10:59:05.552Z",
  "senderId": "Any sender id",
  "message": "Any message text",
  "batchSize": 0,
  "batchIndex": 0,
  "smsCount": 0,
  "smsParts": 0,
  "beingProcessed": true,
  "custom": "Any custom",
  "validity": 48,
  "sourceInterface": "Any source",
  "parsedNumbers": {
    "valid": [
      "Any"
    ],
    "bad": [
      "Any"
    ],
    "duplicated": [
      "Any"
    ]
  }
}

The Campaign resource can be used to send one or more SMS. These can be sent either straight away or scheduled for the future. The JSON request object will contain the details of the message(s) to be sent and will generate a message batch response containing a URI to allow future queries to discover the status of the message(s).

HTTP Request

POST https://secureapi.fastsms.co.uk/campaign

Parameters

from - The default alphanumeric originator that the message appears to originate from. Can be overridden on a per message basis. This must be either a valid phone number or an alphanumeric value with a maximum length of 11 characters, that may contain letters, numbers and the following special characters: * $ ? ! ” # % & _ - , @ + ''

message - The message content to be sent.

validity - Optional. The default validity period in hours for all messages in this request (defaults to 0 which indicates the MAX allowed). The maximum allowed validity period is 72 hours. Messages which cannot be delivered within the specified time will fail.

sendDate - The scheduled time to send the messages in this request. It cannot be overridden on a per-message basis. The format is yyyy-MM-ddThh:mm:ssZ where y=year, M=month, d=day, T=separator, h=hour, m=min and s=seconds. The value is treated as per ISO 8601 semantics, e.g. without time zone information the value is assumed to be the local time of the server, otherwise as an offset from UTC with Z representing a UTC time.

spread - Optional. Spread the messages over time, the spread time parameter should in seconds.

characterSet - The default character set of the messages to be used when not specified within each message. Valid values are: GSM, Unicode and Auto. When using Auto the most appropriate character set is automatically detected. The default value is GSM. When using auto, if unicode characters are detected, the number of characters available in a message will change from 160 to 70.

name - Optional. An alpha-numeric string, 1-128 characters long, which will be used to name the campaign.

custom - Optional. An alpha-numeric string, 1-20 characters long, which will be used to 'tag' your outgoing message and will appear in delivery reports, thus facilitating filtering of reports.

numbers - The numbers to send this message to. Try to include the international code, for example 44 in the UK.

contacts - Contacts id's to send this message to.

groups - Contact groups id's to send this message to.

Responses

Code Description
201 Successful operation
400 Invalid/Malformed request body or more than 50,000 messages in request
401 No authentication header provided
402 Not enough message credits
403 Failed authentication or not authorised to access feature
404 The specified contact or contact group doesn’t exist
406 Empty message body provided
415 Content type is not supported or unspecified

Get Campaign by ID

curl -X GET "https://secureapi.fastsms.co.uk/campaign/id"
  -H "Authorization: sometestapikey"
const Http = new XMLHttpRequest();

const url = 'https://secureapi.fastsms.co.uk/campaign/id';
Http.open("GET", url);
Http.setRequestHeader('Authorization','sometestapikey');
Http.send();

Http.onreadystatechange = (e) => {
  console.log(Http.responseText)
}

The above command returns JSON structured like this:

{
  "id": 1,
  "name": "Campaign Name",
  "sendDate": "2019-05-07T10:31:36.642Z",
  "senderId": "AnySenderId",
  "message": "Any Message" ,
  "batchSize": 0,
  "batchIndex": 0,
  "smsCount": 0,
  "smsParts": 0,
  "beingProcessed": true,
  "custom": "Any Custom",
  "validity": 0,
  "sourceInterface": "Any Source",
  "parsedNumbers": {
    "valid": [
      "Any"
    ],
    "bad": [
      "Any"
    ],
    "duplicated": [
      "Any"
    ]
  }
}

This endpoint find campaign resource by ID.

HTTP Request

GET https://secureapi.fastsms.co.uk/campaign/id

Parameters

Responses

Code Description
200 Successful operation
401 Forbidden
404 Resource not found

Delete Campaign by ID

curl -X DELETE "https://secureapi.fastsms.co.uk/campaign/id"
  -H "Authorization: sometestapikey"
const Http = new XMLHttpRequest();

const url = 'https://secureapi.fastsms.co.uk/campaign/id';
Http.open("DELETE", url);
Http.setRequestHeader('Authorization','sometestapikey');
Http.send();

Http.onreadystatechange = (e) => {
  console.log(Http.responseText)
}

The above command returns JSON structured like this:

{}

This endpoint remove campaign resource by ID, the campaign may not be in processing.

HTTP Request

DELETE https://secureapi.fastsms.co.uk/campaign/id

Parameters

Responses

Code Description
200 Successful operation
401 Forbidden
423 Campaign locked

Get Campaign Log

curl -X GET "https://secureapi.fastsms.co.uk/campaign/log?page=1&per_page=25"
  -H "Authorization: sometestapikey"
const Http = new XMLHttpRequest();

const url = 'https://secureapi.fastsms.co.uk/campaign/log?page=1&per_page=25';
Http.open("GET", url);
Http.setRequestHeader('Authorization','sometestapikey');
Http.send();

Http.onreadystatechange = (e) => {
  console.log(Http.responseText)
}

The above command returns JSON structured like this:

[
  {
    "id": 0,
    "sendDate": "2019-05-07T10:46:04.313Z",
    "endDate": "2019-05-07T10:46:04.313Z",
    "name": "Any campaign",
    "senderId": "Any sender",
    "message": "Any message text",
    "smsCount": 12,
    "smsParts": 0,
    "amountUsed": 12,
    "active": true,
    "delivered": 7,
    "failed": 5,
    "sent": 12,
    "sourceInterface": "Any"
  }
]

This endpoint list all account campaign log entries.

HTTP Request

GET https://secureapi.fastsms.co.uk/campaign/log?page=1&per_page=25

Parameters

page, per_page_, sort - Pagination

since (string)- Get all campaigns sent since the given date. The format is yyyy-MM-ddThh:mm:ssZ where y=year, M=month, d=day, T=separator, h=hour, m=min and s=seconds. The value is treated as per ISO 8601 semantics, e.g. without time zone information the value is assumed to be the local time of the server, otherwise as an offset from UTC with Z representing a UTC time.

Responses

Code Description
200 Successful operation
401 Forbidden

Get Campaign Log by ID

curl -X GET "https://secureapi.fastsms.co.uk/campaign/log/id"
  -H "Authorization: sometestapikey"
const Http = new XMLHttpRequest();

const url = 'https://secureapi.fastsms.co.uk/campaign/log/id';
Http.open("GET", url);
Http.setRequestHeader('Authorization','sometestapikey');
Http.send();

Http.onreadystatechange = (e) => {
  console.log(Http.responseText)
}

The above command returns JSON structured like this:

{
  "id": 0,
  "sendDate": "2019-05-07T10:46:04.313Z",
  "endDate": "2019-05-07T10:46:04.313Z",
  "name": "Any campaign",
  "senderId": "Any sender",
  "message": "Any message text",
  "smsCount": 12,
  "smsParts": 0,
  "amountUsed": 12,
  "active": true,
  "delivered": 7,
  "failed": 5,
  "sent": 12,
  "sourceInterface": "Any"
}

This endpoint find campaign log resource by ID.

HTTP Request

GET https://secureapi.fastsms.co.uk/campaign/log/id

Parameters

Responses

Code Description
200 Successful operation
401 Forbidden
404 Resource not found

Group

Get Group

curl -X GET "https://secureapi.fastsms.co.uk/group?page=1&per_page=25"
  -H "Authorization: sometestapikey"
const Http = new XMLHttpRequest();

const url = 'https://secureapi.fastsms.co.uk/group?page=1&per_page=25';
Http.open("GET", url);
Http.setRequestHeader('Authorization','sometestapikey');
Http.send();

Http.onreadystatechange = (e) => {
  console.log(Http.responseText)
}

The above command returns JSON structured like this:

[
  {
    "id": 10,
    "name": "groupName"
  }
]

This endpoint list all accounts contact groups entries.

HTTP Request

GET https://secureapi.fastsms.co.uk/group?page=1&per_page=25

Parameters

page, per_page, sort - Pagination

Responses

Code Description
200 Sucessful operation
401 Forbidden

Post Group

curl -X POST "https://secureapi.fastsms.co.uk/group"
  -H "Authorization: sometestapikey"
  -H "Content-Type: application/json"
  -d "{ \"id\": 11, \"name\": \"groupName2\"}
const Http = new XMLHttpRequest();

const url = 'https://secureapi.fastsms.co.uk/group';
Http.open("POST", url);
Http.setRequestHeader("Content-Type", "application/json;charset=UTF-8");
Http.send(JSON.stringify({"id": 11, "name": "groupName2"}));

Http.onreadystatechange = (e) => {
  console.log(Http.responseText)
}

The above command returns JSON structured like this:

{
  "id": 11,
  "name": "groupName2"
}

This endpoint create contact group resource.

HTTP Request

POST https://secureapi.fastsms.co.uk/group

Parameters

Responses

Code Description
201 Sucessful operation
401 Forbidden
412 Duplicate entry

Get Group by ID

curl -X GET "https://secureapi.fastsms.co.uk/group/id"
  -H "Authorization: sometestapikey"
const Http = new XMLHttpRequest();

const url = 'https://secureapi.fastsms.co.uk/group/id';
Http.open("GET", url);
Http.setRequestHeader('Authorization','sometestapikey');
Http.send();

Http.onreadystatechange = (e) => {
  console.log(Http.responseText)
}

The above command returns JSON structured like this:

{
  "id": 11,
  "name": "groupName2"
}

This endpoint find contact group resource by ID.

HTTP Request

GET https://secureapi.fastsms.co.uk/group/id

Parameters

Responses

Code Description
200 Successful operation
401 Forbidden
404 Resource not found

Delete Group by ID

curl -X DELETE "https://secureapi.fastsms.co.uk/group/id"
  -H "Authorization: sometestapikey"
const Http = new XMLHttpRequest();

const url = 'https://secureapi.fastsms.co.uk/group/id';
Http.open("DELETE", url);
Http.setRequestHeader('Authorization','sometestapikey');
Http.send();

Http.onreadystatechange = (e) => {
  console.log(Http.responseText)
}

The above command returns JSON structured like this:

{}

This endpoint remove contact group resource by ID.

HTTP Request

DELETE https://secureapi.fastsms.co.uk/group/id

Parameters

delContacts (boolean) - Delete contacts in group. Default value: false

Responses

Code Description
200 Successful operation
401 Forbidden

Patch Group by ID

curl -X PATCH "https://secureapi.fastsms.co.uk/group/id"
  -H "Authorization: sometestapikey"
  -H "Content-Type: application/json"
  -d "{ \"id\": 11, \"name\": \"groupName3\"}"
const Http = new XMLHttpRequest();

const url = 'https://secureapi.fastsms.co.uk/group/id';
Http.open("PATCH", url);
Http.setRequestHeader("Content-Type","application/json");
Http.send(JSON.stringify({"id": 11, "name": "groupName3"}));

Http.onreadystatechange = (e) => {
  console.log(Http.responseText)
}

The above command returns JSON structured like this:

{
  "id": 11,
  "name": "groupName3"
}

This endpoint update contact group by ID.

HTTP Request

POST https://secureapi.fastsms.co.uk/group/id

Parameters

body (json) - Updated group resource.

Responses

Code Description
200 Successful operation
401 Forbidden
404 Resource not found
412 Duplicate entry

Get Group Contacts

curl -X GET "https://secureapi.fastsms.co.uk/group/id/contact"
  -H "Authorization: sometestapikey"
const Http = new XMLHttpRequest();

const url = 'https://secureapi.fastsms.co.uk/group/id/contact';
Http.open("GET", url);
Http.setRequestHeader('Authorization','sometestapikey');
Http.send();

Http.onreadystatechange = (e) => {
  console.log(Http.responseText)
}

The above command returns JSON structured like this:

[
  {
    "id": 1,
    "number": "0690001122",
    "firstName": "John",
    "surname": "Moore",
    "company": "Commify",
    "email": "john.moore@commify.com",
    "city": "Paris",
    "country": "France",
    "custom1": "Any",
    "custom2": "Any",
    "custom3": "Any",
    "custom4": "Any",
    "custom5": "Any",
    "custom6": "Any",
    "custom7": "Any",
    "custom8": "Any",
    "custom9": "Any",
    "custom10": "Any",
    "stop": true
  }
]

This endpoint list all group contacts.

HTTP Request

GET https://secureapi.fastsms.co.uk/group/id/contact

Parameters

page, per_page, sort - Pagination

Responses

Code Description
200 Successful operation
401 Forbidden

Delete contacts from group by ID

curl -X DELETE "https://secureapi.fastsms.co.uk/group/id/contact"
  -H "Authorization: sometestapikey"
const Http = new XMLHttpRequest();

const url = 'https://secureapi.fastsms.co.uk/group/id/contact';
Http.open("DELETE", url);
Http.setRequestHeader('Authorization','sometestapikey');
Http.send();

Http.onreadystatechange = (e) => {
  console.log(Http.responseText)
}

The above command returns JSON structured like this:

{
  "id": 11,
  "name": "groupName3"
}

This endpoint remove all contacts from group by ID.

HTTP Request

DELETE https://secureapi.fastsms.co.uk/group/id/contact

Parameters

Responses

Code Description
200 Successful operation
401 Forbidden
404 Resource not found

Add contact to group by ID

curl -X PUT "https://secureapi.fastsms.co.uk/group/id/contact/cid"
  -H "Authorization: sometestapikey"
const Http = new XMLHttpRequest();

const url = 'https://secureapi.fastsms.co.uk/group/id/contact/cid';
Http.open("PUT", url);
Http.setRequestHeader('Authorization','sometestapikey');
Http.send();

Http.onreadystatechange = (e) => {
  console.log(Http.responseText)
}

The above command returns JSON structured like this:

{
  "id": 14,
  "name": "groupName4"
}

This endpoint add contact to group by ID.

HTTP Request

PUT https://secureapi.fastsms.co.uk/group/id/contact/cid

Parameters

Responses

Code Description
200 Successful operation
401 Forbidden
404 Resource not found

Remove contact from group by ID

curl -X DELETE "https://secureapi.fastsms.co.uk/group/id/contact/cid"
  -H "Authorization: sometestapikey"
const Http = new XMLHttpRequest();

const url = 'https://secureapi.fastsms.co.uk/group/id/contact/cid';
Http.open("DELETE", url);
Http.setRequestHeader('Authorization','sometestapikey');
Http.send();

Http.onreadystatechange = (e) => {
  console.log(Http.responseText)
}

The above command returns JSON structured like this:

{
  "id": 11,
  "name": "groupName3"
}

This endpoint remove contact from group by ID.

HTTP Request

DELETE https://secureapi.fastsms.co.uk/group/id/contact/cid

Parameters

Responses

Code Description
200 Successful operation
401 Forbidden
404 Resource not found

Incoming

Get Incoming

curl -X GET "https://secureapi.fastsms.co.uk/incoming?page=1&per_page=25"
  -H "Authorization: sometestapikey"
const Http = new XMLHttpRequest();

const url = 'https://secureapi.fastsms.co.uk/incoming?page=1&per_page=25';
Http.open("GET", url);
Http.setRequestHeader('Authorization','sometestapikey');
Http.send();

Http.onreadystatechange = (e) => {
  console.log(Http.responseText)
}

The above command returns JSON structured like this:

[
  {
    "id": 9,
    "date": "2019-05-07T09:22:35.556Z",
    "from": "Any",
    "to": "Any",
    "message": "Any message text"
  }
]

This endpoint list all account incoming messages.

HTTP Request

GET https://secureapi.fastsms.co.uk/incoming?page=1&per_page=25

Parameters

page, per_page, sort - Pagination

since (string) - Get incoming message received since the given date. The format is yyyy-MM-ddThh:mm:ssZ where y=year, M=month, d=day, T=separator, h=hour, m=min and s=seconds. The value is treated as per ISO 8601 semantics, e.g. without time zone information the value is assumed to be the local time of the server, otherwise as an offset from UTC with Z representing a UTC time.

number (string) - Select incoming messages sent to given number.

keyword (string) - Select incoming messages sent to given keyword.

Responses

Code Description
200 Successful operation
401 Forbidden

Get Incoming by ID

curl -X GET "https://secureapi.fastsms.co.uk/incoming/id"
  -H "Authorization: sometestapikey"
const Http = new XMLHttpRequest();

const url = 'https://secureapi.fastsms.co.uk/incoming/id';
Http.open("GET", url);
Http.setRequestHeader('Authorization','sometestapikey');
Http.send();

Http.onreadystatechange = (e) => {
  console.log(Http.responseText)
}

The above command returns JSON structured like this:

{
  "id": 9,
  "date": "2019-05-07T09:22:35.556Z",
  "from": "Any",
  "to": "Any",
  "message": "Any message text"
}

This endpoint retrieves incoming message resource by ID.

HTTP Request

GET https://secureapi.fastsms.co.uk/incoming/id

Parameters

Responses

Code Description
200 Successful operation
401 Forbidden
404 Resource not found

DLR

Get DLR

curl -X GET "https://secureapi.fastsms.co.uk/dlr?page=1&per_page=25"
  -H "Authorization: sometestapikey"
const Http = new XMLHttpRequest();

const url = 'https://secureapi.fastsms.co.uk/dlr?page=1&per_page=25';
Http.open("GET", url);
Http.setRequestHeader('Authorization','sometestapikey');
Http.send();

Http.onreadystatechange = (e) => {
  console.log(Http.responseText)
}

The above command returns JSON structured like this:

[
  {
    "id": 10,
    "sendDate": "2019-05-07T12:18:55.575Z",
    "statusDate": "2019-05-07T12:18:55.575Z",
    "smsParts": 10,
    "phoneNumber": 248985934,
    "custom": "Any",
    "status": "Any",
    "delivered": true,
    "failed": false
  }
]

This endpoint list all account DLR entries.

HTTP Request

GET https://secureapi.fastsms.co.uk/dlr?page=1&per_page=25

Parameters

page, per_page, sort - Pagination

since (string) - Get dlr’s received since the given date. The format is yyyy-MM-ddThh:mm:ssZ where y=year, M=month, d=day, T=separator, h=hour, m=min and s=seconds. The value is treated as per ISO 8601 semantics, e.g. without time zone information the value is assumed to be the local time of the server, otherwise as an offset from UTC with Z representing a UTC time.

custom (string) - Select dlr’s with custom given tag field.

campaign_id (string) - Select dlr’s from campaign ID parameter.

Responses

Code Description
200 Successful operation
401 Forbidden

Get DLR by ID

curl -X GET "https://secureapi.fastsms.co.uk/dlr/id"
  -H "Authorization: sometestapikey"
const Http = new XMLHttpRequest();

const url = 'https://secureapi.fastsms.co.uk/dlr/id';
Http.open("GET", url);
Http.setRequestHeader('Authorization','sometestapikey');
Http.send();

Http.onreadystatechange = (e) => {
  console.log(Http.responseText)
}

The above command returns JSON structured like this:

{
  "id": 10,
  "sendDate": "2019-05-07T12:18:55.575Z",
  "statusDate": "2019-05-07T12:18:55.575Z",
  "smsParts": 10,
  "phoneNumber": 248985934,
  "custom": "Any",
  "status": "Any",
  "delivered": true,
  "failed": false
}

This endpoint find DLR resource by ID.

HTTP Request

GET https://secureapi.fastsms.co.uk/dlr/id

Parameters

Responses

Code Description
200 Successful operation
401 Forbidden
404 Resource not found

Email-to-SMS

Our email-to-SMS service provides a simple way for you to send text messages via email.

There are 3 main ways to use the email to SMS gateway;

Option 1 – To send single emails/messages using domain authentication

Option 2 – To send single emails/messages using api key authentication

Option 3 – To send messages to multiple recipients with a single email (and advanced features)

Domain Authentication

This option is used when you cannot or do not want to transmit your api key in the subject field of the email.

You set your sending domain in your account, e.g. mycompanyname.com which is what we use for validation when the email comes in.

Only emails sent from the domain you set will be accepted (no generic email accounts like Hotmaill or Gmail are acceptable).

In the account settings screen, choose Email Gateway tab.

Under “Email Gateway Settings” enter your domain name (e.g. if your email address was richard@greens.com then your domain name is greens.com) in the field and choose Enable (do not include the @ sign).

Make sure Message termination is also Active. Then click Update.

Email domain auth

Make sure you add ## to the end of the text in the body you want to send (this tells our system that this is the end of the text to send out and avoids sending things like signatures etc).

You can change the message termination string by logging into your account and navigating to Account settings, choose Email Gateway tab, email gateway settings.

You don’t have to put anything in the subject line as it’s not used. Below is an example using domain authentication and sending to a single recipient.

Email2sms 1

Api Key Authentication

To send single emails/messages using api key authentication

This option is exactly the same as option 1 apart from you do not need to turn on domain authentication in your account and instead you use your Api Key in the subject field of the email for authentication.

So your email would look like this:

Email2sms 2

Multiple Recipients

** To send messages to multiple recipients with a single email. **

Email2sms 3

Additional Features

The Email-to-SMS (or email-to-text-message) service allows you to send SMS text messages via email.

You must have an SMS marketing account (you can create a free account here) to send text messages via this service.

The actual email address of the email-to-SMS gateway is shown in the screenshot above (gateway@ and the domain is e2s.fastsms.co.uk).

To send a text message to one or more mobile numbers, you will specify the message to send, and the numbers to send to, in an email. You then send the email to our email-to-sms gateway email address (using a specific format/structure).

Let’s say you want to send a text message containing ‘Call us for a quote’ to the UK mobile number 447777123456. To do this your email contents would look like this:

Call us for a quote##
447777123456

The ‘##’ characters simply tell us that this is the end of the message to be sent. And it’s followed by the mobile number. That’s it!

Multiple Recipients

You want to send a text message via email to more than one mobile number? No problem! Simply list the numbers on separate lines, like this:

Call us for a quote##
447777123456
447777123457

Or put them on the same line, with commas in between to separate the numbers, like this:

Call us for a quote##
447777123456,447777123457

Or you can type the recipients numbers directly into the address bar, like this:

447777123456@e2s.fastsms.co.uk;447777123457@e2s.fastsms.co.uk

Message With Multiple Lines

A message sent using the email-to-SMS gateway can contain more than more line. Simply ensure the message still ends with ‘##’, e.g.:

Special offer this week on:
- black tights
- green shoes##
07777123456

From/Sender ID

The sender ID is the number/name that your text message will appear as being sent from.

When using the email-to-text API this defaults to the sender ID that is set in your account (see the ‘Send SMS’ > ‘Sender ID’).

For example, you might want to set the sender ID as the name of your business, or perhaps to your own mobile number.

The sender ID can be any 16-digit number, or any text of up to 11 alpha-numeric characters.

Examples

Let’s say you want to send the message ‘Special 2-for-1 offer this week’ to the UK mobile number 447777123456, with a sender ID of ‘Fast Pizzas’.

Your email body (contents) would look like this:

Special 2-for-1 offer this week##
Fast Pizzas#
447777123456

The sender ID is ‘terminated’, i.e. ends with, a single ‘#’ character. It can appear before or after the message, so this works too:

Fast Pizzas#
Special 2-for-1 offer this week##
447777123456

Error Reporting

If your email-to-SMS request is successful, with no errors or problems, you will not get any response (unless you’re using the Sandbox service).

However, if there are any problems with the format of your email, or problems sending to any of the numbers you specify in the email, you will get a verbose email response with details of the problem(s) encountered.

Testing/Sandbox

If you want to test the service without actually sending any text messages, there is a different email address to use for this purpose:

sandbox@ followed by the same domain: e2s.fastsms.co.uk

447777123456.sandbox@e2s.fastsms.co.uk

It works in the same way as the normal service, except that no text messages will be sent and therefore no credit will be deducted from your account.

Also, unlike the normal service, you will get a confirmation email telling you what message would have been sent, and to what numbers, if you had used the normal live service.

Errors

HTTP

The FAST SMS uses the following HTTP error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- No authentication header provided.
403 Forbidden -- Failed authentication or not authorised to access feature.
404 Not Found -- The specified resource could not be found.
405 Method Not Allowed -- You tried to access a resource with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
412 Precondition Failed -- Access to the target resource has been denied.
415 Unsupported Media Type -- Content type is not supported or unspecified.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

API

The FAST SMS uses the following API error codes:

HTTP Code Code Message Description
404 1001 Resource not found Resource key supplied don't exist.
412 1007 Duplicate entry Resource already exist, error trying to insert/update duplicate entry.