Quick Start - Notifique

From zero to your first SMS in the queue in a few steps. Start with sk_test_... in Sandbox.

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. Scopes: API Key scopes.

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

POST /v1/sms/messages
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

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

Response (202)

{
  "success": true,
  "data": {
    "status": "QUEUED",
    "count": 2,
    "messageIds": ["clxx123...", "clxx456..."],
    "smsIds": ["clxx123...", "clxx456..."]
  }
}

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

Fewer than 9 characters in payload.message → 400 (SMS_MESSAGE_TOO_SHORT).

Send with template

If you already have a workspace template with SMS enabled, use type: "template", the same pattern as WhatsApp, Telegram, and other channels:

{
  "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

GET /v1/sms/messages?page=1&limit=20
Authorization: Bearer sk_live_xxxxx

{
  "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

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:

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

Cancel (QUEUED or SCHEDULED):

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.

6. Webhooks (optional)

Set up sms.sent, sms.delivered, sms.failed, and MO (sms.received, sms.replied) to track without polling. Guide: Webhook events.

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: when to use and status lifecycle
Scopes: key permissions
Webhook events: real-time status
Error responses: HTTP codes and code

​In brief

​Before you start

​1. Send SMS

​Send with template

​2. List history

​3. Query one send

​4. Schedule and cancel

​5. Avoid duplicates

​6. Webhooks (optional)

​All send types

​Next steps

In brief

Before you start

1. Send SMS

Send with template

2. List history

3. Query one send

4. Schedule and cancel

5. Avoid duplicates

6. Webhooks (optional)

All send types

Next steps