Delay and schedule a send

The delay object holds a message for later. Choose a duration, an exact timestamp, or a recurring window in the recipient’s timezone.

Prerequisites

Delay a send

Delay by a duration

Set delay.duration in milliseconds to hold the message that long from now. Courier sends after exactly that interval (3600000 ms is one hour).

const { requestId } = await client.send.message({
  message: {
    to: { user_id: 'user_123' },
    template: 'nt_01kx4h2jdafq8bk9aftxak4b40',
    delay: { duration: 3600000 },
  },
});

response = client.send.message(
    message={
        "to": {"user_id": "user_123"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "delay": {"duration": 3600000},
    },
)

curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "user_id": "user_123" },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "delay": { "duration": 3600000 }
    }
  }'

response = courier.send_.message(
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    delay: { duration: 3600000 }
  }
)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Delay: courier.SendMessageParamsMessageDelay{
			Duration: courier.Int(3600000),
		},
	},
})

SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(JsonValue.from(java.util.Map.of("user_id", "user_123")))
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .delay(JsonValue.from(java.util.Map.of("duration", 3600000)))
        .build())
    .build();
client.send().message(params);

$response = $client->send->message(
  message: [
    'to' => ['userID' => 'user_123'],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'delay' => ['duration' => 3600000],
  ],
);

SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Delay = new() { Duration = 3600000 },
    },
};

await client.Send.Message(parameters);

courier send message \
  --api-key "$COURIER_API_KEY" \
  --message '{"to":{"user_id":"user_123"},"template":"nt_01kx4h2jdafq8bk9aftxak4b40","delay":{"duration":3600000}}'

With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123 in one hour.

Schedule for a specific time

Set delay.until to an ISO 8601 timestamp to send at an exact moment. A date alone (2026-01-01) is midnight UTC. Include a time and offset for precision (2026-01-01T09:00:00-05:00).

const { requestId } = await client.send.message({
  message: {
    to: { user_id: 'user_123' },
    template: 'nt_01kx4h2jdafq8bk9aftxak4b40',
    delay: { until: '2026-01-01T09:00:00Z' },
  },
});

response = client.send.message(
    message={
        "to": {"user_id": "user_123"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "delay": {"until": "2026-01-01T09:00:00Z"},
    },
)

curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "user_id": "user_123" },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "delay": { "until": "2026-01-01T09:00:00Z" }
    }
  }'

response = courier.send_.message(
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    delay: { until: "2026-01-01T09:00:00Z" }
  }
)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Delay: courier.SendMessageParamsMessageDelay{
			Until: courier.String("2026-01-01T09:00:00Z"),
		},
	},
})

SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(JsonValue.from(java.util.Map.of("user_id", "user_123")))
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .delay(JsonValue.from(java.util.Map.of("until", "2026-01-01T09:00:00Z")))
        .build())
    .build();
client.send().message(params);

$response = $client->send->message(
  message: [
    'to' => ['userID' => 'user_123'],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'delay' => ['until' => '2026-01-01T09:00:00Z'],
  ],
);

SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Delay = new() { Until = "2026-01-01T09:00:00Z" },
    },
};

await client.Send.Message(parameters);

courier send message \
  --api-key "$COURIER_API_KEY" \
  --message '{"to":{"user_id":"user_123"},"template":"nt_01kx4h2jdafq8bk9aftxak4b40","delay":{"until":"2026-01-01T09:00:00Z"}}'

With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123 on January 1 at 9am UTC.

Send within a delivery window

Set delay.until to a recurring window (opening-hours syntax) and Courier holds the message until the next time inside it. This is how you deliver during business hours or at a good local time.It is also how you enforce quiet hours, because a window is the inverse of a do-not-disturb period. A 9am to 9pm window in the recipient’s timezone says “never between 9pm and 9am”. A message arriving outside it waits rather than waking anyone.

const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
      timezone: "America/New_York",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    delay: {
      until: "Mo-Fr 09:00-17:00",
    },
  },
});

response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
            "timezone": "America/New_York",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "delay": {
            "until": "Mo-Fr 09:00-17:00",
        },
    },
)

curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "user_id": "user_123",
        "timezone": "America/New_York"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "delay": {
        "until": "Mo-Fr 09:00-17:00"
      }
    }
  }'

response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123",
      timezone: "America/New_York"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    delay: {
      until: "Mo-Fr 09:00-17:00"
    }
  }
)

// This provider addresses the recipient with fields outside the typed
// UserRecipient model, so pass the recipient as raw JSON.
to := param.Override[shared.UserRecipientParam](json.RawMessage(`{
  "user_id": "user_123",
  "timezone": "America/New_York"
}`))

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{OfUserRecipient: &to},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		// delay: {"until": "Mo-Fr 09:00-17:00"}
	},
})

SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        // This provider addresses the recipient with fields outside the
        // typed UserRecipient model, so pass them as additional properties.
        .to(UserRecipient.builder()
            .userId("user_123")
            .putAdditionalProperty("timezone", JsonValue.from("America/New_York"))
            .build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .delay(JsonValue.from(java.util.Map.of("until", "Mo-Fr 09:00-17:00")))
        .build())
    .build();
SendMessageResponse response = client.send().message(params);

$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
      'timezone' => 'America/New_York',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'delay' => [
      'until' => 'Mo-Fr 09:00-17:00',
    ],
  ],
);

SendMessageParams parameters = new()
{
    Message = new()
    {
        // This provider addresses the recipient with fields outside the
        // typed UserRecipient model, so build it from raw JSON.
        To = UserRecipient.FromRawUnchecked(
            JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                """
                {
                  "user_id": "user_123",
                  "timezone": "America/New_York"
                }
                """
            )
        ),
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Delay = new() { Until = "Mo-Fr 09:00-17:00" },
    },
};

var response = await client.Send.Message(parameters);

courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123", "timezone": "America/New_York"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.delay '{"until": "Mo-Fr 09:00-17:00"}'

With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123 during business hours in their timezone.

Courier resolves the timezone in this order: delay.timezone (highest), then to.timezone or the profile’s zoneinfo, then the profile’s timezone, then UTC. Send an array of recipients with different timezones and each one’s window is computed independently, so a single call delivers at 9 AM local for everyone. Windows accept patterns like Mo-Fr 09:00-17:00, Sa-Su 00:00-23:59, and split schedules (Mo-Fr 09:00-12:00,14:00-18:00).

delay.timezone only applies to a window.
For an ISO until timestamp, the timezone is already in the timestamp. delay.timezone matters only when until is an opening-hours expression.

Check the logs

Send with a delay, then open the message in . A Request Delayed event shows the computed delivery time.

Get started

Send messages

Journeys

Broadcasts

Design

Recipients

Tenants

Monitoring

Workspaces

Resources

Delay and schedule a send

Prerequisites

Delay a send

​Prerequisites

​Delay a send

Prerequisites

Delay a send