Scheduled SMS

Schedule SMS messages to be sent at a specific date and time.

Scheduled messages are queued and automatically sent at the specified time. Credits are reserved at scheduling time and refunded if cancelled.

Endpoint

POST /api/scheduled-messages-direct

Quick Start

Prepare your request

Include a messages array in your request body. Each item should include senderId, phone, message, and scheduledDate (with optional scheduledTime).

Set the schedule time

Use scheduledDate (YYYY-MM-DD) and scheduledTime (HH:mm) in 24-hour format. The API converts this internally to the provider-required format (mm/dd/yyyy hh:mm AM/PM).

Send the request

Make a POST request to /api/scheduled-messages-direct with your API key.

Receive confirmation

You'll get scheduling counts (scheduled, failed, skipped) and per-message results.

Request Body

Field	Type	Required	Description
`messages`	array	Yes	Array of messages to schedule

Each messages[] item supports:

Field	Type	Required	Description
`senderId`	string	Yes	Approved sender ID
`phone`	string	Yes	A single destination phone number
`message`	string	Yes	Message content
`scheduledDate`	string	Yes	Date in `YYYY-MM-DD` format
`scheduledTime`	string	No	Time in `HH:mm` format (defaults to 08:00)

The senderId must belong to the same account as the API key and be active. Requests using a sender ID that is not owned by the API key will be rejected.

Request Example

{
  "messages": [
    {
      "senderId": "MyBusiness",
      "phone": "233200000000",
      "message": "Reminder: Your appointment is tomorrow at 10:00 AM",
      "scheduledDate": "2026-04-10",
      "scheduledTime": "10:00"
    },
    {
      "senderId": "MyBusiness",
      "phone": "233201111111",
      "message": "Reminder: Your appointment is tomorrow at 10:00 AM",
      "scheduledDate": "2026-04-10",
      "scheduledTime": "10:00"
    }
  ]
}

Response

Success Response

HTTP/1.1 200 OK

{
  "success": true,
  "scheduled": 2,
  "failed": 0,
  "skipped": 0,
  "results": [
    {
      "phone": "233200000000",
      "status": "scheduled",
      "messageId": "msg_sch_abc123",
      "scheduledFor": "04/10/2026 10:00 AM"
    }
  ],
  "totalCreditsUsed": 2,
  "creditsRemaining": 998,
  "message": "Scheduled 2 messages, failed 0, skipped 0. Used 2 credits."
}

Response Fields

Field	Type	Description
`success`	boolean	Request successful
`scheduled`	number	Number of messages successfully scheduled
`failed`	number	Number of messages that failed
`skipped`	number	Number of messages skipped validation/rules
`results`	array	Per-message scheduling result details
`totalCreditsUsed`	number	Total credits deducted for this scheduling batch
`creditsRemaining`	number	Remaining credits after deduction
`message`	string	Summary message

Date/Time Format

Use scheduledDate and scheduledTime exactly as shown below.

Field	Valid	Example
`scheduledDate`	✅	`2026-04-10`
`scheduledTime`	✅	`10:00`
`scheduledTime`	✅	`08:30`
`scheduledTime`	❌	`10:00 AM`
`scheduledDate`	❌	`10/04/2026`

Provider verification: direct probe tests against sms.gonlinesites.com rejected 24-hour schedule strings with code: "109" (Invalid Schedule Time). The accepted provider format is mm/dd/yyyy hh:mm AM/PM, which is applied internally by this API.

Debugging Schedule Format

Use the probe script to test schedule formats directly against the provider:

npm run test:schedule-format -- --to 233200000000 --from YourApprovedSenderId

The script:

Uses SMS_API_KEY (or SMS_PROVIDER_API_KEY) from .env
Tests multiple schedule formats
Prints provider response codes/messages
Reports the accepted format when detected

Scheduling Rules

📋

Important scheduling constraints: Minimum lead time: 5 minutes in the future Default time: If scheduledTime is omitted, 08:00 is used

Canceling Scheduled Messages

To delete a scheduled message record:

DELETE /api/scheduled-messages-direct/{id}

Cancel Response

{
  "success": true,
  "message": "Message record deleted successfully",
  "warning": "Message may still be sent by SMS provider as scheduled"
}

💡

Note: This endpoint removes your local scheduled record. If the message was already accepted by the provider, delivery may still occur.