# read\_mail

Read the caller's waiting mail, oldest first.

writes · not idempotent · MCP tool · [Agent](https://komrad.dev/latest/api/agent.md)

Reading claims the mail, so a second call returns nothing. Passing another agent's id claims that agent's mail.

## Calling it

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

```bash
komrad rpc read-mail
```

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

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

## Request

### ReadMailRequest

| Field | Type | Description |
| --- | --- | --- |
| [`id`](https://komrad.dev/latest/api/agent/read-mail.md#komrad-agent-v1-ReadMailRequest-id) | uuid | The agent whose unread mail to read, by id. Unset reads the caller's own. |

## Response

### ReadMailResponse

| Field | Type | Description |
| --- | --- | --- |
| [`mail`](https://komrad.dev/latest/api/agent/read-mail.md#komrad-agent-v1-ReadMailResponse-mail) | [Mail\[\]](https://komrad.dev/latest/api/agent/read-mail.md#komrad-agent-v1-Mail) | All the unread mail, oldest first, now marked read. |

## Types

### Mail

Mail is one message in an agent's mailbox.

| Field | Type | Description |
| --- | --- | --- |
| [`id`](https://komrad.dev/latest/api/agent/read-mail.md#komrad-agent-v1-Mail-id) | uuid\* | The mail's id. Pass it as [`reply_to`](https://komrad.dev/latest/api/agent/read-mail.md#komrad-agent-v1-Mail-reply_to) to answer. |
| [`from_agent_id`](https://komrad.dev/latest/api/agent/read-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/read-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/read-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/read-mail.md#komrad-agent-v1-Mail-body) | string | The mail's text. |
| [`reply_to`](https://komrad.dev/latest/api/agent/read-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/read-mail.md#komrad-agent-v1-Mail-created_at) | timestamp | When the mail was sent. |
| [`claimed_at`](https://komrad.dev/latest/api/agent/read-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/read-mail.md#komrad-agent-v1-Mail-expires_at) | timestamp | When the mail expires, read or not. |
| [`kind`](https://komrad.dev/latest/api/agent/read-mail.md#komrad-agent-v1-Mail-kind) | [MailKind](https://komrad.dev/latest/api/agent/read-mail.md#komrad-agent-v1-MailKind) | Who wrote the mail and why. |

### MailKind

MailKind is who wrote a piece of mail and why.

| Value | Description |
| --- | --- |
| [`plain`](https://komrad.dev/latest/api/agent/read-mail.md#komrad-agent-v1-MailKind-plain) | Mail from an agent or the person. |
| [`review_activity`](https://komrad.dev/latest/api/agent/read-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/read-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/read-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/read-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/read-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/read-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/read-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/read-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/read-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/read-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/read-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/read-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/read-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/read-mail.md#komrad-agent-v1-MailKind-worktree_shrunk) | From komrad: komrad deleted build output from the agent's worktree while its task was archived. |
