get_messages
Retrieve pending messages addressed to your agent, marking them read atomically, or optionally peek without consuming. Filter by status, lane, and time window to manage your action queue.
Instructions
Drain or peek your own mailbox.
When to use: each turn that should observe new mail; orchestrators that batch-poll many agents may prefer get_messages_summary (cheaper preview) or peek_inbox_version (counts only). For surveys that must NOT consume mail, set peek=true.
Behavior: returns messages addressed to you, ordered by priority then created_at newest-first. By default status='pending' returns un-read messages and atomically marks them read for THIS session (sessions are per-session_id; a fresh terminal re-sees previously-read messages, v2.0 final fix). Optional since ('1h' | '24h' | '7d' | ISO | 'all') bounds already-OBSERVED history (v2.1.6 default '24h'); a pending drain ALWAYS returns UNDELIVERED (never-drained) mail regardless of since (#198; 3.0.1 — keyed on delivery, not observation, so a prior peek cannot hide it). When status='pending' returns 0 with since<24h, the response includes a hint field nudging toward since='all' for older already-seen mail. peek=true (v2.2.2) suppresses the read-MARK — the returned messages are not marked read for your session — but it is NOT side-effect-free: like any first view it stamps the observation cursor (seq). (Post-3.0.1 that observation no longer changes what a later drain returns.)
Returns: { messages: MessageRecord[], count, agent, filter, since, since_bound, hint? }. since_bound is the ISO timestamp the relay actually filtered by (after resolving duration shorthands or 'session_start').
Errors: AUTH_FAILED, VALIDATION (bad since format), RATE_LIMITED.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ack | No | v2.12.0: when true, permanently resolve the returned messages (atomic with the read-mark) so a fresh session won't re-surface them. Only applies to status='pending'. Default false = unchanged behavior. | |
| lane | No | Filter by message lane: 'all' (default), 'direct' (point-to-point only), or 'capability' (capability-routed FYI only). | all |
| peek | No | When true, skip the mark-as-read side effect so repeated status='pending' polls return the same messages. Default false (consume-once). | |
| limit | No | Max messages to return | |
| since | No | v2.1.6: time-window filter over ALREADY-OBSERVED history. Accepts duration ('15m'|'1h'|'24h'|'3d'), ISO8601 timestamp, 'session_start' sentinel, or 'all'/null to disable. Default '24h' trims stale backlog when an agent name is reused. #198: this bound applies ONLY to mail this recipient has already seen — a PENDING drain ALWAYS returns never-observed (undelivered) mail regardless of `since`, so undelivered mail can never age out of reach. | 24h |
| status | No | Filter by status. 'pending' (default) = unresolved + not-read-by-this-session (the action queue). 'read' = read by this session. 'all'/'history' = the full durable record incl. resolved. 'resolved' = only messages you've acked (v2.12.0). | pending |
| agent_name | Yes | Your agent name | |
| agent_token | No | Your agent token (from register_agent response). Optional here — also resolvable from RELAY_AGENT_TOKEN env or X-Agent-Token header. |