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
  • Delay object: Override with delay.timezone (highest priority)
  • Request level: Override with message.to.timezone
  • User profile: Override with timezone or zoneinfo key in user profile
  • Formats: IANA timezones (America/New_York) or UTC offset (UTC-5)
Timezone Priority Order:
  1. message.delay.timezone (highest priority)
  2. message.to.timezone or user profile zoneinfo
  3. User profile timezone
  4. UTC (default)
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

​
Timezone in Delay Object

You can specify timezone directly in the delay object, which takes precedence over user profile timezone settings. This is especially useful when sending without user profiles. Priority order for timezone resolution:
  1. message.delay.timezone (highest priority)
  2. message.to.timezone or user profile zoneinfo
  3. User profile timezone
  4. UTC (default)
When to use delay.timezone:
  • Sending to recipients without user profiles (just email or phone_number)
  • Overriding user profile timezone for specific messages
  • Ensuring consistent timezone behavior across multiple recipients
Example - Delivery window with delay.timezone: 
{
  "message": {
    "to": {
      "email": "[email protected]"
    },
    "template": "business-update",
    "delay": {
      "until": "Mo-Fr 09:00-17:00",
      "timezone": "America/Los_Angeles"
    }
  }
}
This will deliver the message during business hours (Monday-Friday, 9 AM - 5 PM) in Pacific Time, regardless of user profile settings. Example - Sending without user profiles: 
{
  "message": {
    "to": {
      "email": "[email protected]"
    },
    "template": "reminder",
    "delay": {
      "until": "Mo-Fr 09:00-17:00",
      "timezone": "America/New_York"
    }
  }
}
You don’t need to create user profiles - just provide email or phone_number in the to field and specify timezone in delay.timezone.
Timezone Field Behavior: The delay.timezone field only applies when delay.until is an opening hours expression (e.g., “Mo-Fr 09:00-17:00”). For ISO timestamp until values, timezone is already included in the timestamp.

​
Delivery Window Examples

Business hours with timezone in delay object: 
{
  "message": {
    "to": {
      "email": "[email protected]"
    },
    "template": "business-update",
    "delay": {
      "until": "Mo-Fr 09:00-17:00",
      "timezone": "America/Los_Angeles"
    }
  }
}
Behavior: Delivers during business hours (Monday-Friday, 9 AM - 5 PM) in Pacific Time, regardless of user profile settings. Send Thursday at noon → delivers immediately. Send Saturday at noon → delays until Monday 9:00 AM. Business hours with timezone in to object: 
{
  "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. Sending without user profiles using delay.timezone: 
{
  "message": {
    "to": {
      "email": "[email protected]"
    },
    "template": "reminder",
    "delay": {
      "until": "Mo-Fr 09:00-17:00",
      "timezone": "America/New_York"
    }
  }
}
Behavior: You don’t need to create user profiles - just provide email or phone_number in the to field and specify timezone in delay.timezone. The message will be delivered during business hours in Eastern Time. 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 [email protected] 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