Receive a message

Last updated Oct 2, 2026

POST /spools/{spool}/queues/{queue}/recv

Leases a visible message. wait long-polls until a message becomes visible or the wait elapses (204). The payload returns raw; the lease and message attributes ride Spooler-* response headers. Responses carry Cache-Control no-store. A draining queue keeps serving receives until its backlog empties.

Sample

curl -si -X POST "$SPOOLER_API/spools/<spool>/queues/<queue>/recv" \
  -H "Authorization: Bearer $SPOOLER_KEY"

Parameters

Name	In	Type	Required	Description
spool	path	IdentName, 1–63 chars, ^[A-Za-z0-9_:-]+$	yes	The spool name.
queue	path	IdentName, 1–63 chars, ^[A-Za-z0-9_:-]+$	yes	The queue name.
waitSeconds	query	integer, 0–20	no	Seconds to wait for a message before returning 204, at most 20. Absent waits the maximum; 0 returns immediately.

Responses

Status	Description
200	A message was leased.
204	No message became visible within the wait window.
400	The request is malformed; the kind names the problem.
401	The API key is missing or not recognized.
402	The account is suspended.
403	A plan limit refuses the operation; the kind names it. A 403 without a kind, on any operation, means the API key is blocked.
404	The spool or queue does not exist; the kind says which.
409	Concurrent state refuses the operation; the kind names it.
429	The per-account request rate cap is exceeded. The body names the kind (rate_limited); the wait is the Retry-After header and is not repeated in the body. Headers are as structured as the body, and this one is the header HTTP defines for a wait.
503	The spool is momentarily unavailable.

200 headers

Header	Description
Spooler-Lease	Present back to ack, nack or renew.
Spooler-Message-Id	The message's id.
Spooler-Message-Retries	Redeliveries so far; 0 on the first delivery.
Spooler-Lease-Expires-At	When the lease auto-nacks (RFC 3339, UTC). Absent when the queue has no lease timeout.

429 headers

Header	Description
Retry-After	Seconds until the next request is admitted, whole and at least 1; always the delay-seconds form, never an HTTP-date.