Skip to main content
The Notify API allows you to schedule messages for delivery at a specific time in the future. This is particularly useful for marketing campaigns, time-sensitive announcements, and messages that need to be sent during business hours.

​
Basic scheduling

Schedule a message by including the schedule_at parameter in your request: 
const response = await client.notify.send({
  template_id: "template_01k8ap1btqf5r9fq2c8ax5fhc9",
  to: "+33612345678",
  schedule_at: "2024-12-25T10:00:00Z",
  variables: { 
    promotion: "Holiday Sale" 
  },
});

console.log(response.schedule_at); // When the message will actually be sent
The schedule_at parameter must be:
  • In RFC3339 format with timezone
  • In the future (past times will be rejected)
  • Within the allowed scheduling window (see below)
The API response will include a schedule_at field showing when the message will actually be sent, in RFC3339 format with timezone offset. For example: "2025-10-24T04:58:02-04:00" (includes the -04:00 timezone offset).

​
Scheduling windows

Marketing messages can be scheduled up to 90 days in advance, giving you flexibility for planning long-term campaigns.
Example: Schedule a campaign 30 days in advance
{
  "template_id": "template_01k8ap1btqf5r9fq2c8ax5fhc9",
  "to": "+33612345678",
  "schedule_at": "2025-01-15T14:00:00Z",
  "variables": {
    "campaign": "New Year Sale"
  }
}

​
Automatic compliance enforcement

When scheduling marketing messages, Prelude automatically enforces compliance rules at delivery time. If your scheduled time falls outside allowed hours or on public holidays, messages will be automatically rescheduled to the next available time slot.
For detailed information about time window restrictions, public holiday handling, and automatic scheduling behavior, see the Marketing Compliance documentation.

​
Timezone handling

Scheduling is based on UTC time in the API, but compliance rules are enforced based on the recipient’s local timezone.
1

You provide UTC time

Send your scheduled time in UTC or with a timezone offset
2

Prelude determines recipient timezone

The recipient’s timezone is determined from their phone number
3

Compliance rules are checked

Time windows and holiday restrictions are checked in the recipient’s local time
4

Automatic adjustment if needed

If the time violates rules, it’s automatically moved to the next valid slot

​
Example with timezone conversion

// Your server is in PST, recipient is in France (CET)
const response = await client.notify.send({
  template_id: "template_marketing_abc123",
  to: "+33612345678",
  // 7pm PST = 4am CET (next day)
  schedule_at: "2024-12-15T19:00:00-08:00",
  variables: { message: "Good morning!" }
});

// Automatically adjusted to 8am CET (allowed time)
console.log(response.schedule_at); // "2024-12-16T08:00:00+01:00"

​
Expiration and scheduling

You can combine schedule_at with expires_at to set both when a message should be sent and when it should no longer be attempted: 
const response = await client.notify.send({
  template_id: "template_01k8ap1btqf5r9fq2c8ax5fhc9",
  to: "+33612345678",
  schedule_at: "2024-12-25T09:00:00Z",  // Send at 9am
  expires_at: "2024-12-25T18:00:00Z",   // Give up after 6pm
  variables: { promo: "One Day Sale" }
});
Make sure expires_at is after schedule_at. The expiration window starts from the scheduled delivery time, not from when you make the API call.

​
Cancelling scheduled messages

Currently, scheduled messages cannot be cancelled through the API once submitted. Plan your campaigns carefully and test with small batches first.
If you need to cancel a large scheduled campaign, contact Prelude support immediately.

​
Monitoring scheduled messages

Scheduled messages appear in your webhook events when they are actually sent:
  1. Immediate: transactional.message.created - Message accepted and scheduled
  2. At delivery time: transactional.message.pending_delivery - Message being sent
  3. After delivery: transactional.message.delivered or transactional.message.failed
The correlation_id field in webhooks helps you track messages across their lifecycle.

​
Error codes

Error CodeDescription
invalid_date_formatThe schedule_at timestamp format is invalid
schedule_at_in_pastThe scheduled time is in the past
schedule_at_too_farScheduled time exceeds the maximum window (90 days)
Time window violations for marketing messages don’t generate errors - they result in automatic rescheduling.