Acknowledge a message and send another

Last updated Sep 4, 2026

POST /spools/{spool}/queues/{queue}/ack-and-send

Atomically completes the delivery the lease names and appends the request body to the path's queue — a pipeline step handing its result to the next stage, with no window where the input is acked and the output is missing, or the reverse. The two queues may differ or be the same. Send's headers apply: Spooler-Delay postpones the new message, a dedup key deduplicates it. Retries need no dedup key: a retry of a committed call fails with 410 and appends nothing, and a redelivery after a lost lease means the first call never committed. A dedup hit refuses the whole call (409 kind dedup_claimed, the original id in the body) and acks nothing — ack explicitly if folding into the existing message was the intent. The spool's message cap does not apply (the call is net zero); the byte cap refuses only growth past the limit.

Sample

curl -X POST "$SPOOLER_API/spools/<spool>/queues/<queue>/ack-and-send" \
  -H "Authorization: Bearer $SPOOLER_KEY" \
  -H "Spooler-Lease: <lease>" \
  --data-binary '<payload>'

Parameters

Name	In	Type	Required	Description
spool	path	IdentName, 1–64 chars, ^[A-Za-z0-9_:-]+$	yes	The spool name.
queue	path	IdentName, 1–64 chars, ^[A-Za-z0-9_:-]+$	yes	The queue the new message is sent to.
handle	query	boolean	no	When true, the response carries a signed handle to the fresh message.
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 new message becomes visible, at most a week (168h). Omitted or 0 means immediately visible.
Spooler-Dedup-String	header	string, 1–128 chars, ^[\x21-\x7E]+$	no	The new message's dedup key, as on send. A hit inside the queue's dedup window refuses the whole call with 409.
Spooler-Dedup-Hash	header	string, 32 chars, ^[0-9a-fA-F]{32}$	no	The new message's 16-byte dedup fingerprint, hex-encoded, as on send.

Request body

Required; application/octet-stream.

Responses

Status	Description
201	Acknowledged and appended durably.
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.
411	The request has no Content-Length.
413	The message exceeds the size limit.
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.
507	The new message would grow the spool's payload bytes past its plan's maximum (kind spool_full). An equal or smaller message always passes, so a full spool can still drain.

429 headers

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