Delay

You can delay a request so it executes after a specified time. This works for both the v2 REST API and the legacy zeplo.to proxy.

REST API

Set the delay field (in seconds) when enqueuing a request:

curl -X POST "https://api.zeplo.io/queues/enqueue" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "POST",
    "url": "https://your-api.com/send-reminder",
    "body": "{\"user_id\": 42}",
    "delay": 1800
  }'

This will execute the request after 30 minutes (1800 seconds).

Headers

You can also set delay via request headers. This is useful when you can’t modify the JSON body.

Header	Description
`X-Zeplo-Delay`	Delay in seconds
`X-Zeplo-Delay-Until`	Unix timestamp to delay until

Precedence: body delay > X-Zeplo-Delay header > X-Zeplo-Delay-Until header.

# Delay 60 seconds via header
curl -X POST "https://api.zeplo.io/queues/enqueue" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Zeplo-Delay: 60" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "POST",
    "url": "https://your-api.com/webhook"
  }'

# Delay until a specific time via header
curl -X POST "https://api.zeplo.io/queues/enqueue" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Zeplo-Delay-Until: 1711900800" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "POST",
    "url": "https://your-api.com/webhook"
  }'

zeplo.to Proxy (v1 compatible)

If you use the zeplo.to proxy, you can pass delay as URL query parameters:

Parameter	Description
`_delay`	Delay in seconds
`_delay_until`	Unix timestamp to delay until

Precedence: _delay query param > X-Zeplo-Delay header > _delay_until query param > X-Zeplo-Delay-Until header.

# Delay 30 seconds
curl https://zeplo.to/https://your-api.com/webhook?_token=YOUR_TOKEN&_delay=30

# Delay until a specific unix timestamp
curl https://zeplo.to/https://your-api.com/webhook?_token=YOUR_TOKEN&_delay_until=1711900800

Examples

Use case	delay
Send welcome email 5 min after signup	`300`
Reminder notification after 1 hour	`3600`
Delete temp data after 24 hours	`86400`
30-day account cleanup	`2592000`

How it works under the hood

≤ 15 minutes — The request is held in the queue with a native delay. Execution is near-instant once the delay expires.
> 15 minutes — The request is scheduled via a one-time timer that fires at the exact delay time, then enqueues the request for immediate execution.

Both paths are handled automatically. You just set the delay and Zeplo picks the optimal routing.

Combining delay with retry

If a delayed request fails, retries begin immediately after the first execution attempt (not after another delay). The delay only applies to the initial execution.