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

# Scheduled Messages

> Schedule SMS messages for future delivery

## Overview

Schedule messages to be sent at a specific date and time. Scheduled messages remain in a `pending` state until their scheduled time, when they are queued for delivery.

## Create Scheduled Message

```bash cURL theme={null}
curl -X POST https://api-message.nativehub.live/api/v1/scheduled-messages \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+8801712345678",
    "to": "+8801812345679",
    "body": "Your appointment is tomorrow at 10 AM",
    "scheduled_at": "2026-02-15T10:00:00Z"
  }'
```

```javascript Node.js theme={null}
const response = await fetch('https://api-message.nativehub.live/api/v1/scheduled-messages', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    from: '+8801712345678',
    to: '+8801812345679',
    body: 'Your appointment is tomorrow at 10 AM',
    scheduled_at: '2026-02-15T10:00:00Z'
  })
});

const scheduled = await response.json();
console.log(scheduled);
```

```python Python theme={null}
from datetime import datetime, timezone

response = requests.post(
    'https://api-message.nativehub.live/api/v1/scheduled-messages',
    headers={
        'Authorization': 'Bearer YOUR_API_TOKEN',
        'Content-Type': 'application/json'
    },
    json={
        'from': '+8801712345678',
        'to': '+8801812345679',
        'body': 'Your appointment is tomorrow at 10 AM',
        'scheduled_at': '2026-02-15T10:00:00Z'
    }
)

scheduled = response.json()
print(scheduled)
```

**Response:**

```json theme={null}
{
  "id": "sched_abc123",
  "from": "+8801712345678",
  "to": "+8801812345679",
  "body": "Your appointment is tomorrow at 10 AM",
  "scheduled_at": "2026-02-15T10:00:00Z",
  "status": "pending",
  "created_at": "2026-02-14T15:30:00Z"
}
```

## Scheduled Time Format

<Warning>
  The `scheduled_at` field must be in ISO 8601 format with timezone information. Always use UTC (Z suffix) for consistency.
</Warning>

**Valid formats:**

* `2026-02-15T10:00:00Z` (UTC)
* `2026-02-15T10:00:00+00:00` (UTC with offset)
* `2026-02-15T15:00:00+05:00` (Local time with offset)

**Invalid:**

* `2026-02-15 10:00:00` (missing timezone)
* `2026-02-15` (date only)

The server automatically converts all scheduled times to UTC for processing.

## List Scheduled Messages

```bash cURL theme={null}
curl -X GET https://api-message.nativehub.live/api/v1/scheduled-messages \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

```javascript Node.js theme={null}
const response = await fetch('https://api-message.nativehub.live/api/v1/scheduled-messages', {
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN'
  }
});

const scheduled = await response.json();
```

```python Python theme={null}
response = requests.get(
    'https://api-message.nativehub.live/api/v1/scheduled-messages',
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'}
)

scheduled = response.json()
```

## Cancel Scheduled Message

Only messages with `pending` status can be cancelled.

```bash cURL theme={null}
curl -X POST https://api-message.nativehub.live/api/v1/scheduled-messages/sched_abc123/cancel \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

```javascript Node.js theme={null}
const response = await fetch(
  'https://api-message.nativehub.live/api/v1/scheduled-messages/sched_abc123/cancel',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_TOKEN'
    }
  }
);

const result = await response.json();
```

```python Python theme={null}
response = requests.post(
    'https://api-message.nativehub.live/api/v1/scheduled-messages/sched_abc123/cancel',
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'}
)

result = response.json()
```

<Note>
  Messages transition from `pending` to `queued` approximately 1 minute before their scheduled time. Once queued, they cannot be cancelled.
</Note>

## Status Lifecycle

| Status      | Description                                      |
| ----------- | ------------------------------------------------ |
| `pending`   | Waiting for scheduled time (can be cancelled)    |
| `queued`    | Processing started, waiting for carrier delivery |
| `delivered` | Successfully delivered to recipient              |
| `failed`    | Delivery failed (see error codes)                |
| `cancelled` | Cancelled by user before sending                 |

## Timezone Handling

The API accepts scheduled times in any timezone but converts them to UTC internally. When retrieving scheduled messages, all times are returned in UTC.

**Example: Schedule for 3 PM Bangladesh time (UTC+6)**

```javascript Node.js theme={null}
// Local time: 2026-02-15 15:00:00 in Dhaka (UTC+6)
// Converts to: 2026-02-15 09:00:00 UTC

const scheduledAt = new Date('2026-02-15T15:00:00+06:00').toISOString();
// Result: "2026-02-15T09:00:00.000Z"

await fetch('https://api-message.nativehub.live/api/v1/scheduled-messages', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    from: '+8801712345678',
    to: '+8801812345679',
    body: 'Reminder: Event at 3 PM today',
    scheduled_at: scheduledAt
  })
});
```

```python Python theme={null}
from datetime import datetime
from zoneinfo import ZoneInfo

# Local time: 2026-02-15 15:00:00 in Dhaka (UTC+6)
local_time = datetime(2026, 2, 15, 15, 0, 0, tzinfo=ZoneInfo('Asia/Dhaka'))
scheduled_at = local_time.isoformat()
# Result: "2026-02-15T15:00:00+06:00"

response = requests.post(
    'https://api-message.nativehub.live/api/v1/scheduled-messages',
    headers={
        'Authorization': 'Bearer YOUR_API_TOKEN',
        'Content-Type': 'application/json'
    },
    json={
        'from': '+8801712345678',
        'to': '+8801812345679',
        'body': 'Reminder: Event at 3 PM today',
        'scheduled_at': scheduled_at
    }
)
```