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
`to`	string	Destination address (recipient)
`from`	string	Source address (originator)
`message`	string	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
`dlrUrl`	url	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.
`priority`	string	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
`scheduled`	string	Schedule message sending in specified time. Date and time must be set in ISO 8601 ex.: 2015-01-01T13:00:00+02:00
`udh`	string	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 hereand here for SMS concatenation. Attention If you specify `udh` - automatic message splitting will be disabled and you will also have to include field `coding`.
`coding`	integer	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).
`testMode`	string	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
`expireIn`	integer	Use this to set time in seconds after which the message expires (is not attempted sent anymore). Values can be in range [360, 432000].
`correctBy`	string	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
`id`	integer	Unique message identifier, which was returned after submitting a message for sending.
`status`	integer	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.
`error`	integer	You can find all VertexSMS API error codes here
`mcc`	string	If available you will get mobile country code, more info here
`mnc`	string	If available you will get mobile network 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
`id`	integer	Unique sms identifier, which was returned after submitting an sms was submited.
`scheduled`	string	Date and time in UTC timezone
`from`	string	Source address (originator)
`to`	string	Destination address (recipient)
`message`	string	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.
`dlrUrl`	string	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.