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

# Delays & Delivery Windows

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:

```json theme={null}
{
  "message": {
    "to": {"user_id": "user_123"},
    "template": "reminder-notification",
    "delay": {"duration": 120000},  // 2 minutes
    "data": {
      "task_name": "Review quarterly report"
    }
  }
}
```

<Note>
  **Timing Precision**: Duration values are rounded up to the next minute. For example, 90 seconds (90000ms) will be rounded to 2 minutes.
</Note>

**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](https://en.wikipedia.org/wiki/ISO_8601) timestamp format:

**Date only (midnight UTC):**

```json theme={null}
{
  "message": {
    "to": {"user_id": "user_123"},
    "template": "new-year-announcement",
    "delay": {"until": "2025-01-01"}
  }
}
```

**Date and time with timezone:**

```json theme={null}
{
  "message": {
    "to": {"user_id": "user_123"},
    "template": "meeting-reminder",
    "delay": {"until": "2024-12-15T09:00:00-05:00"}
  }
}
```

**UTC timestamp:**

```json theme={null}
{
  "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`

### Delivery Window Examples

<Note>
  **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.
</Note>

**Business hours with timezone in delay object:**

```json theme={null}
{
  "message": {
    "to": {
      "email": "user@example.com"
    },
    "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "message": {
    "to": {
      "email": "user@example.com"
    },
    "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:**

```json theme={null}
{
  "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.*

<Note>
  **Limited Opening Hours Support**: Courier supports basic time windows but not advanced features like holidays or exceptions. Contact [support@courier.com](mailto:support@courier.com) if you need more complex scheduling rules.
</Note>

## Monitoring

### Message Logs

When a delay is accepted, the Message Log shows a `Request Delayed` event with delivery timing details:

```json theme={null}
{
  "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](/platform/analytics/message-logs) to verify scheduled messages and troubleshoot delivery timing.

## Related Resources

<CardGroup cols={2}>
  <Card title="Message Logs" href="/platform/analytics/message-logs" icon="chart-line">
    Monitor scheduled messages and verify delay behavior
  </Card>

  <Card title="Send API Reference" href="/api-reference/send/send-a-message" icon="book">
    Complete API documentation for delay configuration
  </Card>

  <Card title="User Profiles" href="/api-reference/user-profiles/get-a-profile" icon="user">
    Learn how to set user timezone preferences
  </Card>

  <Card title="Automations" href="/platform/automations/automations-overview" icon="robot">
    Create complex time-based notification workflows
  </Card>
</CardGroup>