Skip to main content
Message delays allow you to schedule notification delivery for a future time instead of sending immediately. This enables time-sensitive communications, business hour compliance, and user experience control by delivering messages at the most appropriate times.

​
Key Concepts

​
Delay Types

Courier supports three methods for delaying message delivery:
  1. Duration delay: Delay by a specific amount of time (e.g., 2 hours from now)
  2. Timestamp delay: Schedule delivery for an exact date and time
  3. Delivery window: Send only during specified business hours or time periods

​
Common Use Cases

  • Reminder notifications: Send follow-up messages after a delay
  • Business hour compliance: Ensure messages arrive during working hours
  • Time zone configuration: Deliver at appropriate local times for users
  • Campaign scheduling: Schedule promotional messages for optimal timing
  • Workflow automation: Coordinate message timing with business processes

​
Configuration

​
Duration Delay

Delay message delivery by a specific number of milliseconds from the current time: 
{
  "message": {
    "to": {"user_id": "user_123"},
    "template": "reminder-notification",
    "delay": {"duration": 120000},  // 2 minutes
    "data": {
      "task_name": "Review quarterly report"
    }
  }
}
Timing Precision: Duration values are rounded up to the next minute. For example, 90 seconds (90000ms) will be rounded to 2 minutes.
Common duration examples:
  • 5 minutes: 300000 (5 × 60 × 1000)
  • 1 hour: 3600000 (60 × 60 × 1000)
  • 1 day: 86400000 (24 × 60 × 60 × 1000)

​
Timestamp Delay

Schedule message delivery for a specific date and time using ISO 8601 timestamp format: Date only (midnight UTC): 
{
  "message": {
    "to": {"user_id": "user_123"},
    "template": "new-year-announcement",
    "delay": {"until": "2025-01-01"}
  }
}
Date and time with timezone: 
{
  "message": {
    "to": {"user_id": "user_123"},
    "template": "meeting-reminder",
    "delay": {"until": "2024-12-15T09:00:00-05:00"}
  }
}
UTC timestamp: 
{
  "message": {
    "to": {"user_id": "user_123"},
    "template": "system-maintenance",
    "delay": {"until": "2024-12-15T14:00:00Z"}
  }
}

​
Delivery Window

Send messages only during specified time periods using business hour rules. Based on current time and the delivery window, Courier automatically determines whether to send immediately or delay until the next valid time window. Timezone Support:
  • Default: UTC timezone
  • User profile: Override with timezone key in user profile
  • Request level: Override with message.to.timezone
  • Formats: IANA timezones (America/New_York) or UTC offset (UTC-5)
Time Range Behavior:
  • Inclusive start: Messages sent exactly at window start time are delivered
  • Exclusive end: Messages sent exactly at window end time are delayed to next window
Common Patterns:
  • Business hours: Mo-Fr 09:00-17:00
  • Weekends only: Sa-Su 00:00-23:59
  • Morning hours: Mo-Fr 08:00-12:00
  • Split schedule: Mo-Fr 09:00-12:00,14:00-18:00
  • Specific day: Mo 09:00-17:00

​
Delivery Window Examples

Business hours with timezone: 
{
  "message": {
    "to": {
      "user_id": "user_123",
      "timezone": "America/Los_Angeles"
    },
    "template": "business-update",
    "delay": {
      "until": "Mo-Fr 08:00-16:30"
    }
  }
}
Behavior: Send Thursday at noon → delivers immediately. Send Saturday at noon → delays until Monday 8:00 AM. Multiple recipients with different timezones: 
{
  "message": {
    "to": [
      {
        "user_id": "west_coast_user",
        "timezone": "America/Los_Angeles"
      },
      {
        "user_id": "east_coast_user", 
        "timezone": "America/New_York"
      }
    ],
    "template": "team-announcement",
    "delay": {
      "until": "Mo-Fr 08:00-16:30"
    }
  }
}
Behavior: Each user’s delivery is calculated independently based on their timezone.
Limited Opening Hours Support: Courier supports basic time windows but not advanced features like holidays or exceptions. Contact support@courier.com if you need more complex scheduling rules.

​
Monitoring

​
Message Logs

When a delay is accepted, the Message Log shows a Request Delayed event with delivery timing details: 
{
  "delay": {
    "duration": 120000
  },
  "details": {
    "duration": "Message delivery has been delayed by 2 minutes.",
    "date": "The message will be delivered on October 09, 2024 at 8:36 GMT+00:00"
  }
}
Use Message Logs to verify scheduled messages and troubleshoot delivery timing.

Message Logs

Monitor scheduled messages and verify delay behavior

Send API Reference

Complete API documentation for delay configuration

User Profiles

Learn how to set user timezone preferences

Automations

Create complex time-based notification workflows