Skip to content

Simple SMS API

Our SMS API is able to parse requests coming in as either JSON, Form-encoded or even as a querystring.

However, some caution must be taken when building a form/querystring request, especially when it comes to lists, as each list needs an index.

Building a Request

1
2
3
GET /rest/mtsms?message=Hello+World&recipients.0.msisdn=4512345678&sender=ExampleSMS HTTP/1.1
Host: gatewayapi.com
Authorization: Basic R28tQ3JlYXRlLWFuLUFQSS10b2tlbjo=

1
2
3
4
5
6
7
POST /rest/mtsms HTTP/1.1
Host: gatewayapi.com
Authorization: Basic R28tQ3JlYXRlLWFuLUFQSS10b2tlbjo=
Content-Type: application/x-www-form-urlencoded
Content-Length: 99

message=Hello+World&recipients.0.msisdn=4512345678&sender=ExampleSMS

This is a request with the following fields:

  • The message itself Hello World
  • The recipient 4512345678
  • The sender ExampleSMS

As recipients are an array of objects, the format becomes {array_name}.{index}.{object_field}. Or in this specific case recipients.{index}.msisdn.

To demonstrate how to build requests, we have included two examples using curl below. The data in the examples are the same as above, but broken up into more lines where it makes sense, rather than the plain HTTP requests above.

1
2
3
4
5
curl -X GET \
    --user Go-Create-an-API-token \
    -G message=Hello World \
    -G recipients.0.msisdn=4512345678 \
    -G sender=ExampleSMS

1
2
3
4
5
curl -X POST \
    --user Go-Create-an-API-token \
    -F message=Hello World \
    -F recipients.0.msisdn=4512345678 \
    -F sender=ExampleSMS

Input Fields

Field Type Required Note
message string yes The message of the SMS
recipients.0.msisdn int yes The receiving phone number
sender string no The sender text
encoding string no The desired encoding of the message
user_ref string no Your reference for the SMS
callback_url string no The URL we deliver notifications back to

These fields are the same as in Basic Use in the REST docs, which is because the HTTP GET/POST API is merely a specialized parser for the same API.

For the complete list of fields that can be used, consult the Advanced Use.

Multiple Recipients

When sending to multiple recipients the array index increases by one for each element in the array.

1
2
3
GET /rest/mtsms?message=Hello+World&recipients.0.msisdn=4512345678&recipients.1.msisdn=4587654321&sender=ExampleSMS HTTP/1.1
Host: gatewayapi.com
Authorization: Basic R28tQ3JlYXRlLWFuLUFQSS10b2tlbjo=

1
2
3
4
5
6
7
POST /rest/mtsms HTTP/1.1
Host: gatewayapi.com
Authorization: Basic R28tQ3JlYXRlLWFuLUFQSS10b2tlbjo=
Content-Type: application/x-www-form-urlencoded
Content-Length: 99

message=Hello+World&recipients.0.msisdn=4512345678&recipients.1.msisdn=4587654321&sender=ExampleSMS

1
2
3
4
5
6
curl -X GET \
    --user Go-Create-an-API-token \
    -G message=Hello World \
    -G recipients.0.msisdn=4512345678 \
    -G recipients.1.msisdn=4587654321 \
    -G sender=ExampleSMS

1
2
3
4
5
6
curl -X POST \
    --user Go-Create-an-API-token \
    -F message=Hello World \
    -F recipients.0.msisdn=4512345678 \
    -F recipients.1.msisdn=4587654321 \
    -F sender=ExampleSMS

Recommendations

Use a trusted encoding library. Adding strings will probably work in most cases, but a proper URL encoding function would make sure your message is not rejected due to some trivial problem - for example a message with an ampersand (&) in it.