REST SMS API
Connect with the world
Our REST API provides an easy-to-use
and easy-to-implement interface for receiving
and submitting messages from and to the gateway.
Start sending SMS today
SMS Gateway REST API
The Mobile Messaging SMS Gateway provides an easy-to-use and easy-to-implement REST API for submitting SMS to and receiving DLR from the gateway.
This manual will describe the interface and provide some examples on how to use this interface. If you have further questions regarding this interface, please contact your account manager or file a trouble ticket to support@gtx-messaging.com.
Sending SMS
Endpoint
You can reach the SMS Gateway under the following URL using HTTPs on port 443:
https://rest.gtx-messaging.net/smsc/sendsms/:auth-key[/:format]
Note: Due to data protection reasons the API is only accessible via HTTPs with TLS versions 1.2.
Path Parameters
| Path Parameter | Mandatory | Type | Description | Example |
|---|---|---|---|---|
| auth-key | yes | String | Your personal API Key, provided in GTX Dashboard | "aaaaaaaa-bbbb-cccc-dddd-1234567890ab" |
| format | no | String | Sets the output format for the SMSC response. Allowed: "json", "xml", "plain". Default is "plain" | "json" |
HTTP Methods
The allowed request methods for sending SMS are GET, POST or PUSH.
| Key | Value | Mandatory | Type | Description | Example |
|---|---|---|---|---|---|
| Accept | application/x-www-form-urlencoded | no | String | Set "plain" output format | "Accept: application/x-www-form-urlencoded" |
| Accept | application/json | no | String | Set "json" output format | "Accept: application/json" |
| Content-Type | application/x-www-form-urlencoded | no | String | Sets plain format for the request parameters | "Content-Type: application/x-www-form-urlencoded" |
| Content-Type | application/json | no | String | Sets json format for the request parameters | "Content-Type: application/json" |
Note: Default Content-Type is for “Content-Type: application/x-www-form-urlencoded”.
Request Parameters
The following HTTP-GET, HTTP-POST or HTTP-PUSH parameters can be set to submit a message:
| Field | Mandatory | Type | Description | Example |
|---|---|---|---|---|
| from | yes | String | The TPOA / originator of the message. Allowed is alphanumeric up to 11 chars, shortcode, local longcode or international number (E.164, E.212 or E.214) | "Company" "+49171000000" "01729000000" "55888" |
| to | yes | String | The recipient of the message, international format, with leading "+" (E.164, E.212 or E.214) | "+49171000000" |
| text | yes | String | Content of the message | "Hello World" |
| dlr-mask | no | Number | Request for delivery reports with the state of the sent message. The value is a bit mask composed of: 1: Delivered to phone 2: Non-Delivered to Phone 34: Expired 66: Unknown |
"3" (bit mask) for Status "DELIVRD", "UNDELIV" and "EXPIRED" |
| dlr-url | no | String | If dlr-mask is given, this mandatory URL will be fetched by HTTP-GET method. | "https://mydomain.com:12345/dlr?" |
| udh | no | String | User Data Header (UDH) part of the message, HEX encoded. | "0605040B8423F0" |
| dcs | no | Number | Data Coding Scheme (DCS) in HEX | "0" for text msg, "8" for binary |
| mclass | no | Number | Message Class; accepted values: 0 to 3 | "0" for submit display |
| mwi | no | Number | Message Waiting Indicator (MWI) sets the MWI bits in DCS | |
| coding | no | Number | Sets the coding scheme bits in DCS field. Accepts values 0 to 2 | "0" 7-Bit Message, "1" 8-Bit Message, "2" UCS-2 |
| charset | no | String | Encoding of the message parameter | "UTF-16" |
| validity | no | Number | Validity Period (VP) in minutes | "240" |
| validity-time | no | ISO-8601 | Validity Date Time | "2019-05-01T12:00:00Z" |
| deferred | no | Number | Deferred Delivery Time (DDT) in minutes | "5" |
| deferred-time | no | ISO-8601 | Deferred Delivery Date Time | "2019-05-01T12:00:00Z" |
Response
As a result you will receive following HTTP status codes and body:
| HTTP Status | HTTP Code | Response Fields | Retriable |
|---|---|---|---|
| HTTP_OK | 200 | <message-count>, <message-status>, <message-id> | NO |
| HTTP_BAD_REQUEST | 400 | Error list for details | NO |
| HTTP_UNAUTHORIZED | 401 | Error list for details | NO |
| HTTP_FORBIDDEN | 403 | Error list for details | NO |
| HTTP_INTERNAL_SERVER_ERROR | 500 | Error list for details | YES |
Please note: GTX General SMS REST API gateway accepts long messages and split them where needed.
Hence please always read <message-count> returned by gateway.
Receiving DLRs
Description of the parameters signalling delivery reports (DLR):
| Field | Type | Description | |
|---|---|---|---|
| from | String | Phone number of the receiver. | |
| to | String | Phone number of the sender. | |
| message-id | String | Message ID of the submitted message | |
| dlr-mask | Number | State of the sent message. The value is a bit mask composed of: 1: Delivered to phone, 2: Non-Delivered to Phone, 34: Expired, 66: Unknown |
|
| error-code | Number | Error code | |
| error-message | String | Error message | |
| submit-date | ISO-8601 | Timestamp of submission | |
| done-date | ISO-8601 | Timestamp of delivery | |
| plmn | Number | Public Land Mobile Number (PLMN): Networkcode (MCC+MNC) of the sent SMS | |
| country | ISO 3166-1 alpha-2 | two-letter country code of the destination of the SMS | |
| sms-cost | Decimal | SMS price charged (price for single SMS) |
Notes:
1) “from” and “to” fields are swapped in delivery reports
2) Client always has to respond with HTTP_OK and body: „OK“
Successful Sending
URL for sending one message and request delivery reports to signal on "https://www.mydomain.com:12345/dlr_backchannel?"
HTTP-GET-Request with response:
https://rest.gtx-messaging.net/smsc/sendsms/aaaaaaaa-bbbb-cccc-dddd-1234567890ab/json?from=test&to=%2b4917xxxxxxxx&text=test&dlr-mask=3&dlr-url=https%3A%2F%2Fwww.mydomain.com%3A12345%2Fdlr_back channel%3F
Or UCS2 Request:
https://rest.gtx-messaging.net/smsc/sendsms/aaaaaaaa-bbbb-cccc-dddd1234567890ab/json?from=test&to=%2b4917xxxxxxxx&text=просто+тест&coding=3&charset=utf-8&dlr_mask=3&dlr_url=https%3A%2F%2Fwww.mydomain.com%3A12345%2Fdlr_backchannel%3F
The same UCS2 Request without charset parameter (text in UCS2):
https://rest.gtx-messaging.net/smsc/sendsms/aaaaaaaa-bbbb-cccc-dddd-1234567890ab/json?from=test&to=%2b491729084747&text=%04%3f%04%40%04%3e%04%41%04%42%04%3e%00%20%04%42%04%35%04%41%04%42&coding=3&dlr-mask=7&dlr-url=https%3A%2F%2Fwww.mydomain.com%3A12345%2Fdlr_backchannel%3F
GTX gateway response HTTP_OK, the result is JSON formatted
{"message-count":"1","message-status":"OK","message-id":"44ca4150-7382-4e17-91a6-599628dca12e"}
Client Response HTTP_OK:
OK
Failed Sending
Request ("from"-parameter missing):
https://rest.gtx-messaging.net/smsc/sendsms/aaaaaaaa-bbbb-cccc-dddd-1234567890ab/json?to=%2b491729084747&text=test&dlr-mask=3&dlr-url= https%3A%2F%2Fwww.mydomain.com%3A12345%2Fdlr_backchannel%3F
GTX gateway response HTTP_BAD_REQUEST:
{"from":["can't be blank","is too short (minimum is 1 character)"]}
Simple HTTP API
Want to set up our Simple HTTP API (v1.x)? Feel free to have a look at our HTTP API Docs.
If you have any questions regarding your setup, please feel free to reach out to our sales team or contact our support team at support@gtx-messaging.com.
Download manual
