# SMS API

This guide will help you integrate SMS capabilities into your applications, enabling you to send, receive, and manage SMS messages seamlessly.

## **Send SMS**

The Send SMS API in Unecast allows you to send SMS messages (Single Message or Multi Message) to your recipients. This API is designed to be simple and straightforward, enabling you to integrate SMS capabilities into your applications quickly.

### **Request**

```json
Endpoint: /v1.0/sms/send
Method: POST

// Request Headers:
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

// Request Body: JSON object
{
"from": "UNECAST",
"to": "1234567890",
"message": "Hello, this is a test message from Unecast!"
}
```

### **Response**

```json
{
"status": "success",
"message_id": "abcd1234",
"from": "UNECAST",
"to": "1234567890",
"message": "Hello, this is a test message from Unecast!",
"timestamp": "2024-06-29T12:34:56Z",
}
```

### Example Use Case

#### **Sending an SMS to one or multiple destination numbers**

To send an SMS, send a `POST` request to the `/sms/send` endpoint. Here’s an example using `curl`:

```json
curl -X POST https://api.unecast.com/v1.0/sms/send \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
           "from": "UNECAST",
           "to": "1234567890,1234567891",
           "message": "Hello, this is a test message from Unecast!"
         }'
```

#### Handling Responses

* **Success**: If the request is successful, you will receive a `200 OK` status with the relevant data in the response body.
* **Error**: If there is an error, you will receive an appropriate HTTP status code and an error message detailing the issue.

**Example Success Response**

A successful response will look like this:

```json
{
    "status": "success",
    "data": [
        {
            "message_id": "1ff9c6c0000a1487af1c",
            "message_count": 1,
            "from": "UNECAST",
            "to": "1234567890",
            "message": "Hello, this is a test message from Unecast!",
            "timestamp": "2024-07-31T02:40:08.492Z"
        },
        {
            "message_id": "1ff9c6c0000bb796bdee",
            "message_count": 1,
            "from": "UNECAST",
            "to": "1234567891",
            "message": "Hello, this is a test message from Unecast!",
            "timestamp": "2024-07-31T02:40:08.492Z"
        }
    ]
}
```

**Example Error Response**

If there is an error, the response might look like this:

```json
{
  "status": "error",
  "message": "Invalid phone number",
  "code": "400"
}
```

#### Best Practices

* **Message Content**: Ensure your messages comply with regulatory standards and best practices for SMS content.
* **Rate Limiting**: Be mindful of rate limits to avoid throttling and ensure smooth message delivery.
* **Error Handling**: Implement robust error handling in your application to manage API errors gracefully.

***

## Check SMS Status

### Request

```json
Endpoint: /v1.0/sms/status/{message_id}
Method: GET

// Request Headers:
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

```

### Response

```json
{
"status": "delivered",
"message_id": "abcd1234",
"to": "1234567890",
"timestamp": "2024-06-29T12:35:56Z"
}
```

***

## Tutorials

### **Sending Your First SMS**

1. **Create an App**: Sign in to Unecast and click on Developer to [`create your first app`](https://app.unecast.com/developer/create).
2. **Select Project Scope**: Select REST API to generate an API key
3. **Send an SMS**: Use the `/sms/send` endpoint to send your first SMS.
4. **Check Status**: Use the `/sms/status/{message_id}` endpoint to check the delivery status of your message.