# REST API — Sending SMS


Source: https://vertexsms.com/en/api/sms

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

Submits message(s) for sending. On success returns HTTP `200 OK` and an array of IDs of the 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 `udh` is not used, length is unlimited — messages are split automatically. With `udh`, max length depends on encoding. |

## Optional parameters

| Field | Type | Description |
|-------|------|-------------|
| dlrUrl | url | Where to deliver the delivery report for each submitted message. The report contains the same message ID returned at submission. |
| priority | string | `high` (registration codes, password reminders, urgent SMS), `normal` (default), `low` (mass messages). |
| scheduled | string | Schedule sending in ISO 8601 format, e.g. `2015-01-01T13:00:00+02:00`. |
| udh | string | User Data Header for long/concatenated messages. Each hex pair must be prefixed with `%`. If you specify `udh`, automatic splitting is disabled and you must also include `coding`. |
| coding | integer | Message encoding. `0` = GSM-7 (default), `1` = 8-bit, `2` = UCS-2. If you specify `coding`, automatic splitting is disabled and you must also include `udh` if the message exceeds the per-encoding character limit (160 GSM-7 / 70 UCS-2). |
| testMode | string | Test the API without sending a real message. `1` = emulate success delivery, `2` = emulate failed delivery. |
| expireIn | integer | Seconds after which the message expires. Range `[360, 432000]`. |
| correctBy | string | Fix recipient number for a given country. Example: `6xxxxxxx` → `3706xxxxxxx` if `LT` is passed. ISO 3166-1 alpha-2 country code. |

### 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 contains up to 160 characters. If you include unicode characters (Chinese, Cyrillic, etc.) the API switches to UCS-2 (`coding=2`) and the maximum shrinks to 70 characters per part.

Longer text is split into parts. Each part is billed as a separate SMS at the same per-destination rate. When split, a User Data Header (UDH) is added to each part for transparent reassembly on the recipient's device, reducing per-part capacity to 153 (GSM-7) or 67 (UCS-2) characters.

If the message contains at least one non-GSM-7 character, the entire message is treated as unicode (UCS-2).

The `X-VertexSMS-Amount-Sent` response header reports the actual number of SMS parts sent.

Some GSM-7 characters take 14 bits and count as 2 characters: `[`, `]`, `~`, `€`, and others.

## Delivery reports (DLRs)

After a send attempt, VertexSMS performs a POST to your `dlrUrl` with a JSON delivery receipt.

Example (when `dlrUrl=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:

| Field | Type | Description |
|-------|------|-------------|
| id | string | Unique message identifier returned at submission. |
| status | integer | `1` = delivered. `2` = not delivered (see `error`). `16` = sent, but delivery period expired. |
| error | integer | VertexSMS error code (see Error codes section). |
| mcc | string | Mobile country code, when available. |
| mnc | string | Mobile network code, when available. |

**Your DLR endpoint MUST respond `200 OK` with body `OK`.** Otherwise the callback is considered failed and is retried until it succeeds.

## Scheduled sendings

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

Request:

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

Response:

```
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 sending fields: `id` (sms identifier), `scheduled` (UTC datetime), `from` (originator), `to` (recipient), `message` (body), `dlrUrl` (delivery-report URL).