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

# Schedule SMS

> Send SMS later, change its delivery time, or cancel it

Set `scheduled_at` to create an SMS now and release it for delivery at a future time.

## Schedule a message

For a new send, `scheduled_at` accepts an ISO 8601 timestamp or a relative value such as `in 5 min`:

```bash theme={null}
curl --request POST \
  --url https://api.dugble.com/sms \
  --header "Authorization: Bearer $DUGBLE_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: appointment-sms-42" \
  --data '{
    "to": "+233201234567",
    "from": "Dugble",
    "body": "Your appointment starts in one hour.",
    "scheduled_at": "2026-08-12T09:00:00Z"
  }'
```

Relative scheduling is also supported:

```json theme={null}
{
  "scheduled_at": "in 30 min"
}
```

Supported relative units include seconds, minutes, hours, and days. The resolved delivery time must be at least 30 seconds in the future.

## Reschedule an SMS

Use `PATCH /sms/{message_id}` while the SMS is still queued and outside the final mutation cutoff. Rescheduling requires an ISO 8601 timestamp; relative values are not accepted.

```bash theme={null}
curl --request PATCH \
  --url https://api.dugble.com/sms/49a3999c-0ce1-4ea6-ab68-afcd6dc2e794 \
  --header "Authorization: Bearer $DUGBLE_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: appointment-sms-42-reschedule" \
  --data '{
    "scheduled_at": "2026-08-12T11:00:00Z"
  }'
```

## Cancel a scheduled SMS

```bash theme={null}
curl --request POST \
  --url https://api.dugble.com/sms/49a3999c-0ce1-4ea6-ab68-afcd6dc2e794/cancel \
  --header "Authorization: Bearer $DUGBLE_API_KEY" \
  --header "Idempotency-Key: appointment-sms-42-cancel"
```

## Scheduling rules

* Initial schedules must be at least 30 seconds in the future.
* Rescheduling and cancellation are blocked during the final 15 seconds before delivery.
* Only queued messages with a future `scheduled_at` value can be changed or canceled.
* Messages that have already begun processing cannot be changed.
* Use a distinct `Idempotency-Key` for each distinct scheduling mutation.

<Warning>
  The scheduled time controls when Dugble releases the SMS for delivery. Provider and carrier processing can add latency after that point.
</Warning>