# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.unecast.com/rest-api/sms-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.