Inspect a message

Last updated Oct 2, 2026

POST /spools/{spool}/inspect

Reads the message the handle names, in whatever state it is, without moving it: the payload as the body, its attributes as headers. An inspect 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 -si -X POST "$SPOOLER_API/spools/<spool>/inspect" \
  -H "Authorization: Bearer $SPOOLER_KEY" \
  -H "Spooler-Handle: <handle>"

Parameters

Name	In	Type	Required	Description
spool	path	IdentName, 1–63 chars, ^[A-Za-z0-9_:-]+$	yes	The spool name.
Spooler-Handle	header	Handle, 16–256 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. 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.
410	The lease no longer settles anything: expired, already settled, or predates a primary change.
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-Message-Id	The message's id.
Spooler-Message-State	The state the message is in.
Spooler-Message-Retries	Redeliveries so far.

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.