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 500 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..."],
  }
}

Response includes messageIds.

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. Pick the send type

options.speed sets the carrier route and changes the price. In the dashboard: SMS → New SMS → Send type (SMS Full, SMS Standard, SMS Slow).

Value	Dashboard	What it’s for	Credits	Pay-as-you-go
`full`	SMS Full	OTP, urgent alert	120	R$ 0.15
`standard`	SMS Standard	Default (omit the field)	100	R$ 0.12
`slow`	SMS Slow	Campaign, no rush	70	R$ 0.09

{
  "to": ["5511999999999"],
  "type": "text",
  "payload": { "message": "Today only: 20% off the whole store." },
  "options": { "speed": "slow" }
}

OTP or verification code — use full:

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

Own number: with from (your active purchased line), recipients see your number. Price varies by country (smsOwnNumber in GET /v1/pricing) — options.speed does not apply.

speed is not priority. options.speed picks the route and changes the amount charged. options.priority (high, normal, low) only sets the order in Notifique’s internal queue and changes neither the price nor the carrier route.

A value outside the list returns 400 (options.speed must be full, standard, slow).

6. Avoid duplicates

Idempotency-Key header on POST. Retries within 24 h do not create duplicate sends. See Security and reliability.

7. Webhooks (optional)

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

8. Localization and variables

localization (off | manual | ai) + i18n translate payload.message per recipient.
Root variables substitute {{placeholders}} in free text.
202 response may include data.localization, data.sandbox, and data.smsSkippedRecipients.

Details: Introduction.

All send types

In the API reference (SMS tab), open Send SMS (POST /v1/sms/messages) and use the playground examples:

Example	What it shows
Text	Default send with `options.priority` and per-send webhook
Template	`type: template` with variables
Full (OTP / urgent)	`options.speed: full`
Slow (campaign)	`options.speed: slow`
Own number	`from` field (different route and price)

Without speed in the body, billing uses standard.

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. Pick the send type

​6. Avoid duplicates

​7. Webhooks (optional)

​8. Localization and variables

​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. Pick the send type

6. Avoid duplicates

7. Webhooks (optional)

8. Localization and variables

All send types

Next steps