Skip to main content
senderkit messages queries the message log — the durable record of every send and its status. The CLI exposes the list endpoint with filters and cursor pagination, paired with --json for piping into jq, spreadsheets, or downstream alerting.

​
senderkit messages list

List messages newest-first. With no flags, returns a recent page across all channels and statuses. 
senderkit messages list [options]

​
Options

​
--limit <number>
Maximum messages to return (a positive integer). The server has its own default and maximum — see the API Reference.
​
--cursor <string>
Pagination cursor. Use the nextCursor from a previous response to fetch the next page.
​
--status <string>
Filter by status, e.g. queued, rendered, sent, delivered, failed, opted_out.
​
--channel <email|sms|push|web-push>
Filter by channel.
​
--template <slug>
Filter by template slug, e.g. welcome.
​
--metadata <json>
Filter by the metadata you attached at send time, as a JSON object — e.g. '{"orderId":"ord_9"}'. Every key/value pair must match.

​
Examples

# Recent messages, table view
senderkit messages list

# Everything that failed, by email
senderkit messages list --status failed --channel email

# All sends of a specific template
senderkit messages list --template welcome --limit 100

# Filter by metadata attached at send time
senderkit messages list --metadata '{"orderId":"ord_9"}'

# Paginate
senderkit messages list --limit 50
senderkit messages list --limit 50 --cursor "msg_01HZ…"
Human output: 
ID         STATUS     CHANNEL  TEMPLATE        TO                CREATED
msg_01HZ…  delivered  email    welcome         user@example.com  2026-05-28T10:14:02Z
msg_01HY…  failed     email    password-reset  jane@example.com  2026-05-28T10:13:55Z
next cursor: msg_01HX…

​
Scripting with --json

--json emits the full SDK response — a data array and a nextCursor string — which makes jq workflows clean: 
# Count failed messages in the latest page
senderkit messages list --status failed --json | jq '.data | length'

# Pull every recipient that bounced today
senderkit messages list --status failed --json | jq -r '.data[].recipient'

# Walk every page
cursor=""
while :; do
  page=$(senderkit messages list --limit 100 ${cursor:+--cursor "$cursor"} --json)
  echo "$page" | jq '.data[]'
  cursor=$(echo "$page" | jq -r '.nextCursor // empty')
  [ -z "$cursor" ] && break
done

​
senderkit messages get

Fetch a single message by its public ID. 
senderkit messages get <id>
​
id
required
Public message ID, e.g. msg_01HZ… — the id returned by send or a row from messages list.
senderkit messages get msg_01HZ…

id:        msg_01HZ…
status:    delivered
channel:   email
template:  welcome
recipient: user@example.com
openedAt:  2026-05-28T10:16:40Z
clickedAt: —
createdAt: 2026-05-28T10:14:02Z
Add --json for the full message object.

​
senderkit messages cancel

Cancel a still-pending message. Only scheduled or queued messages are cancelable — once a message has moved past that (e.g. sent), the server returns a 409 and the command fails. 
senderkit messages cancel <id>
​
id
required
Public message ID of a scheduled or queued message.
senderkit messages cancel msg_01HZ…

✓ Canceled msg_01HZ…
id:     msg_01HZ…
status: canceled
There’s no live tail (messages tail) in the CLI. For real-time delivery monitoring, use the SSE stream (GET /v1/messages?tail=1) described in the API Reference; from the terminal, poll messages list with a filter.
Messages are retained for a limited window — 3 days on Free, 14 days on Pro. If you need history beyond that, export with --json on a schedule and persist in your own system, correlating via the metadata you attached at send time.

Messages

The lifecycle and retention rules behind these records.

send

Fire a send, then query its status here.

Sending

Why a queued message hasn’t been delivered yet.

API Reference

The list endpoint, status enum, and live tail stream.