> ## Documentation Index
> Fetch the complete documentation index at: https://docs.notifique.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> First SMS send via API: send, query, and cancel scheduled messages.

<Tip>
  From **zero to your first SMS in the queue** in a few steps. Start with `sk_test_...` in [Sandbox](/en/guides/sandbox/index).
</Tip>

## In brief

* **Send** short text (9 to 160 characters) to one or many numbers.
* **Query** history or a single send by id.
* **Cancel** while status is `QUEUED` or `SCHEDULED`.

Context: [Introduction](/en/sms-api/como-funciona/introducao). Scopes: [API Key scopes](/en/sms-api/como-funciona/escopos-da-api-key).

***

## Before you start

| Item                                         | Required                      |
| -------------------------------------------- | ----------------------------- |
| Key with **`sms:send`**                      | Yes                           |
| Numbers in **international** format (no `+`) | Yes                           |
| `sms:read` / `sms:cancel`                    | Only if querying or canceling |

Base URL: `https://api.notifique.dev`. Replace `sk_live_xxxxx` with your key (`sk_test_...` in sandbox).

***

## 1. Send SMS

`to` is always an **array** (up to **100** recipients).

```http theme={null}
POST /v1/sms/messages
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx
```

```json theme={null}
{
  "to": ["5511999999999", "5521988887777"],
  "type": "text",
  "payload": {
    "message": "Your code is 482910. Valid for 10 minutes."
  }
}
```

**Response (202)**

```json theme={null}
{
  "success": true,
  "data": {
    "status": "QUEUED",
    "count": 2,
    "messageIds": ["clxx123...", "clxx456..."],
    "smsIds": ["clxx123...", "clxx456..."]
  }
}
```

`messageIds` is the canonical field. `smsIds` is a compatibility alias.

<Note>
  Fewer than **9 characters** in `payload.message` → **400** (`SMS_MESSAGE_TOO_SHORT`).
</Note>

### Send with template

If you already have a [workspace template](/en/template-api/como-funciona/variaveis-disponiveis-e-crud) with SMS enabled, use `type: "template"`, the same pattern as WhatsApp, Telegram, and other channels:

```json theme={null}
{
  "to": ["5511999999999"],
  "type": "template",
  "payload": {
    "templateId": "TEMPLATE_ID",
    "variables": { "code": "482910", "name": "Maria" }
  }
}
```

The API resolves the template text, substitutes variables, and queues the SMS.

***

## 2. List history

```http theme={null}
GET /v1/sms/messages?page=1&limit=20
Authorization: Bearer sk_live_xxxxx
```

```json theme={null}
{
  "success": true,
  "data": [
    {
      "smsId": "clxx123...",
      "to": "5511999999999",
      "message": "Your code is 482910...",
      "status": "DELIVERED",
      "sentAt": "2025-02-20T14:00:00.000Z",
      "deliveredAt": "2025-02-20T14:00:30.000Z"
    }
  ],
  "pagination": { "total": 42, "page": 1, "limit": 20, "totalPages": 3 }
}
```

***

## 3. Query one send

```http theme={null}
GET /v1/sms/messages/:id
Authorization: Bearer sk_live_xxxxx
```

Same shape as a list item. Requires **`sms:read`**.

***

## 4. Schedule and cancel

**Schedule**, include on the send POST:

```json theme={null}
{
  "to": ["5511999999999"],
  "type": "text",
  "payload": {
    "message": "Reminder tomorrow at 9am."
  },
  "schedule": { "sendAt": "2025-03-01T09:00:00.000Z" }
}
```

**Cancel** (`QUEUED` or `SCHEDULED`):

```http theme={null}
POST /v1/sms/messages/:id/cancel
Authorization: Bearer sk_live_xxxxx
```

Scheduled credits return to the workspace. Scope: **`sms:cancel`**.

***

## 5. Avoid duplicates

**`Idempotency-Key`** header on POST. Retries within 24 h do not create duplicate sends. See [Security and reliability](/en/guides/conceitos/seguranca-e-confiabilidade).

***

## 6. Webhooks (optional)

Set up `sms.sent`, `sms.delivered`, `sms.failed`, and MO (`sms.received`, `sms.replied`) to track without polling.

Guide: [Webhook events](/en/sms-api/como-funciona/eventos-do-webhooks).

***

## All send types

In the API reference (SMS tab), open **Send SMS** and pick an example in the playground: Text, Template, Scheduled, Options.

## Next steps

* [Introduction](/en/sms-api/como-funciona/introducao): when to use and status lifecycle
* [Scopes](/en/sms-api/como-funciona/escopos-da-api-key): key permissions
* [Webhook events](/en/sms-api/como-funciona/eventos-do-webhooks): real-time status
* [Error responses](/en/guides/conceitos/resposta-de-erros): HTTP codes and `code`