Peek a message

Last updated Sep 20, 2026

POST /spools/{spool}/peek

Reads the message the handle names, in whatever state it rests, without moving it: the payload as the body, its attributes as headers. A peek grants no ownership and leaves the handle valid. The handle is fenced to the message as it was minted, so one that has since been delivered, settled, recovered or discarded answers 410 — the view is stale, list again. The state reported is the current one: a delayed message reads as visible once its delay elapsed. Responses carry Cache-Control no-store.

Sample

curl -X POST "$SPOOLER_API/spools/<spool>/peek" \
  -H "Authorization: Bearer $SPOOLER_KEY" \
  -H "Spooler-Handle: <handle>"

Parameters

Name	In	Type	Required	Description
spool	path	IdentName, 1–64 chars, ^[A-Za-z0-9_:-]+$	yes	The spool name.
Spooler-Handle	header	Handle, 16–128 chars, ^[A-Za-z0-9_-]+$	yes	The handle from a listing or a send, presented back.

Responses

Status	Description
200	The message.
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.
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.
503	The spool is momentarily unavailable.

200 headers

Header	Description
Spooler-Message-Id	The message's id.
Spooler-Message-State	The state the message rests in.
Spooler-Retry-Count	Redeliveries so far.

429 headers

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