Skip to main content

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

Click to Download PDF