# Fast SMS Delivery API

This API allows the user to send SMS messages to recipients and handling delivery reports through a specified delivery URL.

***

## Base URL

`https://messaging.thermolinks.com/`

## Endpoints

### Send SMS

**Path**: `/fcgi-bin/jar_http_sai.fcgi`

**HTTP Method**: `POST`

**Headers**

**Mandatory SMS HTTP Parameters:**

* `X-Service`: `string` - The service name. It is used for authentication/authorization and should match the username defined for the client account.
* `X-Password`: `string` - The password used with the service name for authentication/authorization should match the password defined for the client account.
* `X-Recipient`: `string` - The recipient of the message. Multiple recipients are supported (separated by comma).
* `X-Message`: `string` - The message body. This is used in case there is no body content in the HTTP request.

**Optional SMS MT HTTP Parameters:**

* `X-Sender`: `string` - The sender of the message.  If not filled, the default source address set in the client account is used.
* `X-Delivery-URL`: `string` - The URL to which delivery reports are sent. If not filled, the Deliver URL set in the client account is used.
* `X-External-ID`: `string` - The message ID used to correlate messages and corresponding delivery reports. The `X-External-ID` will be sent to the service provider in the corresponding HTTP DR message.
* `X-SMS-DCS`: `integer` - The data coding scheme.
* `Content-Type`: `text/plain` (required) - Content type of the message body.

**Request Body**

Plain text containing the message content.

**Response**

* **Success Response**: HTTP 200 OK
* **Error Response**: Various HTTP error codes as listed below

**Example Request**

```http
POST /fcgi-bin/jar_http_sai.fcgi HTTP/1.1
Host: https://messaging.thermolinks.com
X-Service: SERVICENAME
X-Password: SERVICEPWD
X-Sender: SENDERID
X-Recipient: 2348031234567
X-Delivery-URL: http://webhook.site
X-SMS-DCS: 0
Content-Type: text/plain

Message content in body
```

### HTTP Error Responses

| HTTP Code | HTTP Error Message     |
| --------- | ---------------------- |
| 200       | OK                     |
| 201       | Created                |
| 204       | No Content             |
| 400       | Bad Request            |
| 401       | Authentication Failure |
| 403       | Forbidden              |
| 404       | Not Found              |
| 405       | Method not Supported   |
| 503       | Server Unavailable     |

### Supported Parameters

| Variable                             | Type    | Description                                                                                                                                                                  |
| ------------------------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Mandatory SMS MT HTTP Parameters** |         |                                                                                                                                                                              |
| `X-Service`                          | string  | The service name. It is used for authentication/authorization and should match the username defined in the client account.                                                   |
| `X-Password`                         | string  | The password used with the service name for authentication/authorization and should match the password defined in the client account                                         |
| `X-Recipient`                        | string  | The recipient of the message. Multiple recipients are supported (separated by comma).                                                                                        |
| `X-Message`                          | string  | The message body. This is used in case there is no body content in the HTTP request.                                                                                         |
| **Optional SMS MT HTTP Parameters**  |         |                                                                                                                                                                              |
| `X-Sender`                           | string  | The sender of the message. If not filled, the default source address set in the client account is used.                                                                      |
| `X-Delivery-URL`                     | string  | The URL to which delivery reports are sent. If not filled, the Deliver URL set in the client account is used.                                                                |
| `X-External-ID`                      | string  | The message ID used to correlate messages and corresponding delivery reports. The `X-External-ID` will be sent to the service provider in the corresponding HTTP DR message. |
| `X-SMS-DCS`                          | integer | The data coding scheme.                                                                                                                                                      |

### Delivery Report HTTP Parameters

| Variable                         | Type   | Description                                                                                                                                                      |
| -------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Mandatory DR HTTP Parameters** |        |                                                                                                                                                                  |
| `X-Sender`                       | string | The sender of the message.                                                                                                                                       |
| `X-Recipient`                    | string | The recipient of the message. In case multiple recipients were specified in the original message, one DR HTTP will be sent for each recipient.                   |
| `X-Status`                       | string | The status of the message delivery attempt. It can take the values "DELIVRD", "EXPIRED", "DELETED", "UNDELIV", "UNKNOWN", "ACCEPTD" based on the SMPP DR status. |
| **Other DR HTTP Parameters**     |        |                                                                                                                                                                  |
| `X-Reason`                       | string | A description of the error if the status indicates an error.                                                                                                     |
| `X-External-ID`                  | string | The Tracking ID which was sent in the original MT message.                                                                                                       |

### Sample Delivery Report (DR) Headers

| Header            | Value               |
| ----------------- | ------------------- |
| x-smsc-identifier |                     |
| x-err             | 000                 |
| x-done-date       | 2023-07-13 13:37:00 |
| x-submit-date     | 2023-07-13 13:37:00 |
| x-external-id     | 207229023           |
| x-status          | 200                 |
| x-service         | SERVICENAME         |
| x-sender          | 2348031234567       |
| x-recipient       | THERMOLINKS         |

### Sample Delivery Report (DR) Message

```plaintext
id:207229023 sub:001 dlvrd:000 submit date:2407131337 done date:2407131337 stat:DELIVRD err:000
```

***