# list\_mail

List an agent's mail without claiming it, most recent first.

read-only · idempotent · MCP tool · [Agent](https://komrad.dev/latest/api/agent.md)

Set [`direction`](https://komrad.dev/latest/api/agent/list-mail.md#komrad-agent-v1-ListMailRequest-direction) to list what the agent sent.

## Calling it

```bash
curl -X POST http://127.0.0.1:8787/komrad.agent.v1.AgentService/ListMail \
  -H 'Content-Type: application/json' \
  -d '{}'
```

```bash
komrad rpc list-mail
```

```json
{
  "name": "list_mail",
  "arguments": {}
}
```

Offered by the komrad MCP server to writer, reviewer, orchestrator agents.

## Request

### ListMailRequest

| Field | Type | Description |
| --- | --- | --- |
| [`id`](https://komrad.dev/latest/api/agent/list-mail.md#komrad-agent-v1-ListMailRequest-id) | uuid | The agent whose mail to list, by id. Unset lists the caller's own. |
| [`pagination`](https://komrad.dev/latest/api/agent/list-mail.md#komrad-agent-v1-ListMailRequest-pagination) | [Pagination](https://komrad.dev/latest/api/agent/list-mail.md#komrad-pagination-v1-Pagination) | The page to read. |
| [`direction`](https://komrad.dev/latest/api/agent/list-mail.md#komrad-agent-v1-ListMailRequest-direction) | [MailDirection](https://komrad.dev/latest/api/agent/list-mail.md#komrad-agent-v1-MailDirection) | Whether to list the mail the agent received or sent. |

## Response

### ListMailResponse

| Field | Type | Description |
| --- | --- | --- |
| [`mail`](https://komrad.dev/latest/api/agent/list-mail.md#komrad-agent-v1-ListMailResponse-mail) | [Mail\[\]](https://komrad.dev/latest/api/agent/list-mail.md#komrad-agent-v1-Mail) | One page of mail, newest first. Listing mail does not mark it read. |
| [`next_page_token`](https://komrad.dev/latest/api/agent/list-mail.md#komrad-agent-v1-ListMailResponse-next_page_token) | string | The cursor for the next page. Unset on the last page. |

## Types

### Pagination

Pagination selects one page of a listing.

| Field | Type | Description |
| --- | --- | --- |
| [`limit`](https://komrad.dev/latest/api/agent/list-mail.md#komrad-pagination-v1-Pagination-limit) | int32 at least 0 | How many records to return. Komrad caps the value, and picks one when unset. |
| [`cursor`](https://komrad.dev/latest/api/agent/list-mail.md#komrad-pagination-v1-Pagination-cursor) | string at most 2048 characters | The `next_page_token` from the previous response. Unset to start from the first page. |

### Mail

Mail is one message in an agent's mailbox.

| Field | Type | Description |
| --- | --- | --- |
| [`id`](https://komrad.dev/latest/api/agent/list-mail.md#komrad-agent-v1-Mail-id) | uuid\* | The mail's id. Pass it as [`reply_to`](https://komrad.dev/latest/api/agent/list-mail.md#komrad-agent-v1-Mail-reply_to) to answer. |
| [`from_agent_id`](https://komrad.dev/latest/api/agent/list-mail.md#komrad-agent-v1-Mail-from_agent_id) | uuid | The id of the agent that sent the mail. Unset when komrad sent it. |
| [`from_name`](https://komrad.dev/latest/api/agent/list-mail.md#komrad-agent-v1-Mail-from_name) | string | The sender's name. Mail komrad sent carries komrad's name. |
| [`to_agent_id`](https://komrad.dev/latest/api/agent/list-mail.md#komrad-agent-v1-Mail-to_agent_id) | uuid\* | The id of the agent the mail is for. |
| [`body`](https://komrad.dev/latest/api/agent/list-mail.md#komrad-agent-v1-Mail-body) | string | The mail's text. |
| [`reply_to`](https://komrad.dev/latest/api/agent/list-mail.md#komrad-agent-v1-Mail-reply_to) | uuid | The id of the mail this one answers. Unset when the mail starts a thread. |
| [`created_at`](https://komrad.dev/latest/api/agent/list-mail.md#komrad-agent-v1-Mail-created_at) | timestamp | When the mail was sent. |
| [`claimed_at`](https://komrad.dev/latest/api/agent/list-mail.md#komrad-agent-v1-Mail-claimed_at) | timestamp | When the recipient read the mail. Unset while it is unread. |
| [`expires_at`](https://komrad.dev/latest/api/agent/list-mail.md#komrad-agent-v1-Mail-expires_at) | timestamp | When the mail expires, read or not. |
| [`kind`](https://komrad.dev/latest/api/agent/list-mail.md#komrad-agent-v1-Mail-kind) | [MailKind](https://komrad.dev/latest/api/agent/list-mail.md#komrad-agent-v1-MailKind) | Who wrote the mail and why. |

### MailDirection

MailDirection is whether a listing returns the mail an agent received or sent.

| Value | Description |
| --- | --- |
| [`received`](https://komrad.dev/latest/api/agent/list-mail.md#komrad-agent-v1-MailDirection-received) | The mail sent to the agent. |
| [`sent`](https://komrad.dev/latest/api/agent/list-mail.md#komrad-agent-v1-MailDirection-sent) | The mail the agent sent. |

### MailKind

MailKind is who wrote a piece of mail and why.

| Value | Description |
| --- | --- |
| [`plain`](https://komrad.dev/latest/api/agent/list-mail.md#komrad-agent-v1-MailKind-plain) | Mail from an agent or the person. |
| [`review_activity`](https://komrad.dev/latest/api/agent/list-mail.md#komrad-agent-v1-MailKind-review_activity) | From komrad: a review changed. The mail names the review. |
| [`exchange_capped`](https://komrad.dev/latest/api/agent/list-mail.md#komrad-agent-v1-MailKind-exchange_capped) | From komrad: the agent and one other agent have used up their mail limit with each other. |
| [`document_edited`](https://komrad.dev/latest/api/agent/list-mail.md#komrad-agent-v1-MailKind-document_edited) | From komrad: the person wrote or edited one of the agent's documents. |
| [`pull_request_changed`](https://komrad.dev/latest/api/agent/list-mail.md#komrad-agent-v1-MailKind-pull_request_changed) | From komrad: a pull request on the agent's branch changed on the forge. |
| [`worktree_rebased`](https://komrad.dev/latest/api/agent/list-mail.md#komrad-agent-v1-MailKind-worktree_rebased) | From komrad: komrad rebased the agent's worktree, or tried to. |
| [`worktree_pushed`](https://komrad.dev/latest/api/agent/list-mail.md#komrad-agent-v1-MailKind-worktree_pushed) | From komrad: the agent's branch was force-pushed to origin. |
| [`worktree_aborted`](https://komrad.dev/latest/api/agent/list-mail.md#komrad-agent-v1-MailKind-worktree_aborted) | From komrad: the sequence stopped in the agent's worktree was aborted. |
| [`review_comment`](https://komrad.dev/latest/api/agent/list-mail.md#komrad-agent-v1-MailKind-review_comment) | From komrad: the person commented on the agent's work. The mail carries the comment. |
| [`agent_failed_to_start`](https://komrad.dev/latest/api/agent/list-mail.md#komrad-agent-v1-MailKind-agent_failed_to_start) | From komrad: an agent this agent created exited as its CLI launched. The mail names the agent. |
| [`agent_turn_failed`](https://komrad.dev/latest/api/agent/list-mail.md#komrad-agent-v1-MailKind-agent_turn_failed) | From komrad: a turn of an agent this agent created ended on an error. The mail names the agent. |
| [`guide_requested`](https://komrad.dev/latest/api/agent/list-mail.md#komrad-agent-v1-MailKind-guide_requested) | From komrad: the person asked the agent for a guide to its diff. The mail names the snapshot to explain. |
| [`dormant_mid_turn`](https://komrad.dev/latest/api/agent/list-mail.md#komrad-agent-v1-MailKind-dormant_mid_turn) | From komrad: komrad closed the agent's pane mid-turn to stay inside its memory limit, stopping every process the agent started. |
| [`task_quiet`](https://komrad.dev/latest/api/agent/list-mail.md#komrad-agent-v1-MailKind-task_quiet) | From komrad: every agent on a task whose writer the agent created went quiet with the task neither parked nor waiting on komrad. |
| [`worktree_shrunk`](https://komrad.dev/latest/api/agent/list-mail.md#komrad-agent-v1-MailKind-worktree_shrunk) | From komrad: komrad deleted build output from the agent's worktree while its task was archived. |
