Release a message

Last updated Sep 4, 2026

POST /spools/{spool}/release

Returns the message to its queue without spending a retry — as if the receive never happened; Spooler-Delay postpones its visibility. Release asserts the message was not at fault (a shutdown, a wrong worker, a dependency briefly away); nack is the error path. A release never moves a message toward the failure queue, so a handler that releases on every error retries forever.

Sample

curl -X POST "$SPOOLER_API/spools/<spool>/release" \
  -H "Authorization: Bearer $SPOOLER_KEY" \
  -H "Spooler-Lease: <lease>"

Parameters

Name	In	Type	Required	Description
spool	path	IdentName, 1–64 chars, ^[A-Za-z0-9_:-]+$	yes	The spool name.
Spooler-Lease	header	LeaseToken, 16–128 chars, ^[A-Za-z0-9_-]+$	yes	The lease from a receive, presented back.
Spooler-Delay	header	Duration, ≤ 168h	no	How long until the released message becomes visible, at most a week (168h). Omitted or 0 means immediately visible.

Responses

Status	Description
204	Released.
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.
404	The spool or queue does not exist; the kind says which.
409	Concurrent state refuses the operation; the kind names it.
410	The lease no longer settles anything: expired, already settled, or predates a primary change.
429	The per-account request rate cap is exceeded; retry after the Retry-After delay.
500	The server failed; kind operation_unconfirmed means the write was accepted but its durability is unknown.
503	The spool is momentarily unavailable.

429 headers

Header	Description
Retry-After	Seconds until the next request is admitted.