We use cookies to improve your experience on this site and serve more relevant content to you. By continuing to browse our site you agree to our use of cookies, revised Privacy Policy and Terms of Service.  More information about cookies

Sending SMS

POST https://api.vertexsms.com/sms

Submits message(s) for sending. If successful - returns HTTP status code 200 OK and an array of IDs of messages added to the sending queue.

Required parameters
Field
Type
Description
Field to
Type string
Description Destination address (recipient)
Field from
Type string
Description Source address (originator)
Field message
Type string
Description Message body. If optional parameter udh is not used - length is not limited: messages will be split automatically. Otherwise, max. text length depends on characters used - see here for more info.
Optional parameters
Field
Type
Description
Field dlrUrl
Type url
Description Where to transfer delivery report of each submitted message. Delivery report will contain the same message ID, which is returned after submitting the message for sending.
Field priority
Type string
Description Change priority of sms. Possible values:
• high - use this for registration forms, password reminders and other important sms.
• normal - default priority for sms’es
• low - use this priority for mass messages
Field scheduled
Type string
Description MSchedule message sending in specified time. Date and time must be set in ISO 8601 ex.: 2015-01-01T13:00:00+02:00
Field udh
Type string
Description User Data Header of the message. Used to send long/concatenated messages. Each hex pair should be prefixed with % - see examples. For more info on UDH - see here and here for SMS concatenation.
Attention! If you specify udh - automatic message splitting will be disabled and you will also have to include field coding.
Field coding
Type integer
Description Used to specify encoding of the message text. Possible values:
• 0 - 7 Bits GSM7 Alphabet and more info here
• 1 - 8 Bits
• 2 - UCS-2
Attention! If you specify coding - automatic message splitting will be disabled and you will also have to include field udh if the message exceeds character limit (160 - for text encoded with GSM-7; 70 - with UCS-2).
Field testMode
Type string
Description Use this to test API without sending real message to handset. Possible values:
• 1 - Use this value to emulate success delivery
• 2 - Use this value to emulate failed delivery
Field expireIn
Type integer
Description Use this to set time in seconds after which the message expires (is not attempted sent anymore).
Values can be in range [360, 432000].
Field correctBy
Type string
Description Fix recipient number by a given country. Example: fix the 6xxxxxxx to 3706xxxxxxx if LT country iso passed.
Possible value: country code in ISO 3166-1 alpha-2 format

Request example:

POST /sms HTTP/1.1
Host: api.vertexsms.com
Content-Type: application/json
Accept: application/json
X-VertexSMS-Token: eB52vNTPL9fO3rDrx8pYmVnj6nqceHNhnqceHNh

{ “to”: “37069912345”, “from”: “API”, “message”: “Test SMS 001” }

Response example:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-control: no-cache
X-VertexSMS-Amount-Sent: 1

[”1281532560”]

Message Text, Encoding and Length

A standard SMS (using GSM-7 character set) can contain a maximum of 160 characters.If you will include unicode characters (Chinese, Cyrillic, etc) in your message text - our API will detect that and switch encoding automatically to UCS-2 (coding=2).Unicode characters take up more space, so as a result, maximum length of the message text shrinks to 70 characters.

You can, of course, send text longer than that, however if you do so, our API will automatically split the text into parts.Each split is considered as a separate SMS, and is billed at the same rate as a normal SMS to the same destination.

When message is split into parts, user data headers (UDH) are added to each message, which contain informationabout message concatenation so that all separate parts could be combined as one at the receiving endand the process would be completely transparent to the recipient.

This header takes up some space, this reducing the maximum count of characters a bit more:153 (from 160) for GSM-7 messages and 67 (from 70) for UCS-2 message.

Characters If you use at least one character not from GSM7 alphabet, whole message will be accounted as unicode (UCS-2).
Automatic message splitting The actual number of SMS messages (parts), that the text you provided was split into (and sent to the recipient),can be retrieved from the X-VertexSMS-Amount-Sent response header.
GSM-7 encoding Some GSM-7-encoded characters will take 14 bits, which means such character will be counted as 2 separate characters.These characters include (but are not limited to): []~€ You can find full GSM-7 Alphabet here.
Delivery Reports (DLRS)

After an attempt to send your submitted message(s), Vertex server will perform a POST request to your dlrUrl with POST body containing JSON object with delivery receipt.

Example request (when dlrUrl is set as http://yourserver.com/your_script.php):

POST /your_script.php HTTP/1.1
Host: yourserver.com
Content-Type: application/json

{ “id”: ”1281532560”,”status”: “1”,”error”: 0, “mcc”: “246”, “mnc”: “021” }

DLR fields explanation
Field
Type
Description
Field id
Type string
Description Unique message identifier, which was returned after submitting a message for sending.
Field status
Type integer
Description Possible values:
• 1 - message was delivered.
• 2 - message was not delivered. ErrorCode field will indicate the reason.
• 16 - message was sent, but delivery period has expired.
Field error
Type integer
Description You can find all VertexSMS API error codes here.
Field mcc
Type string
Description If available you will get mobile country code, more info here.
Field mnc
Type string
Description If available you will get mobile country code, more info here.
Your server response Your script, which will handle message delivery reports coming to dlrUrl MUST respond with HTTP status code 200 OK and response body OK. Otherwise, the callback will be considered failed and will be repeated until it succeeds.
Scheduled Sendings

GET https://api.vertexsms.com/sms?scheduled

Request example:

GET /sms?scheduled HTTP/1.1
Host: api.vertexsms.com
Accept: application/json
X-VertexSMS-Token: eB52vNTPL9fO3rDrx8pYmVnj6nqceHNhnqceHNh

Response example:

HTTP/1.1 200 OK
Content-Type: application/json

[{id: “1695684253”,scheduled: “2016-03-16 18:00:00”,from: “Test”,to: “37069559295”,message: “Hello!”,dlrUrl: “http://vertexsms.com”},{id: “1695684559”,scheduled: “2016-03-16 18:00:00”,from: “Test”,to: “37069559295”,message: “Hello!”,dlrUrl: “http://vertexsms.com”}]

Scheduled sendings fields explanation
Field
Type
Description
Field id
Type integer
Description Unique sms identifier, which was returned after submitting an sms was submitted.
Field scheduled
Type integer
Description Date and time in UTC timezone.
Field from
Type integer
Description Source address (originator).
Field to
Type string
Description Destination address (recipient).
Field message
Type string
Description Message body. If optional parameter udh is not used - length is not limited: messages will be split automatically. Otherwise, max. text length depends on characters used - see here for more info.
Field dlrUrl
Type string
Description Where to transfer delivery report of each submitted message. Delivery report will contain the same message ID, which is returned after submitting the message for sending.