list_mail

List the mail addressed to an agent, most recent first, without claiming any of it: unlike read_mail this never empties the mailbox.

Agentread-onlyidempotentMCP tool

claimedAt is unset while a piece is still waiting, and set once the recipient has taken it. id defaults to your own, which is in the KOMRAD_AGENT_ID environment variable; give another agent's id to look at its mailbox instead, which is a deliberate read of somebody else's mail and is recorded as one. Returns one page, pass the response's nextPageToken back as pagination.cursor for the next one. direction says which half of the correspondence to list, the mail addressed to the agent by default, or MAIL_DIRECTION_SENT for the mail it sent. Returns not_found if no agent has that id.

Calling it#

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

komrad rpc list-mail

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

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

Request#

ListMailRequest#

Field	Type	Description
`id`	string	Whose mail to list, or unset for the caller's own.
`pagination`	Pagination	Where to carry on from.
`direction`	MailDirection	Which half of the correspondence to return.

Response#

ListMailResponse#

Field	Type	Description
`mail`	list of Mail	One page of mail, most recent first, none of it claimed by listing it.
`nextPageToken`	string	Pass this back as the pagination cursor for the next page.

Types#

Pagination#

Field Type Description

Field	Type	Description
`limit`	int32	How many rows to return, capped by the server, and left to the server entirely when unset.
`cursor`	string	The next_page_token a previous reply carried, or unset to start from the beginning. at most 2048 characters

limit

int32

How many rows to return, capped by the server, and left to the server entirely when unset.

cursor

string

The next_page_token a previous reply carried, or unset to start from the beginning.

at most 2048 characters

Mail#

Field	Type	Description
`id`	string	Set this as reply_to on an answer so the two read as a thread.
`fromAgentId`	string	Which agent sent it, unset when komrad sent it itself.
`fromName`	string	What to show as the sender, which is komrad's own name for a notice it raised.
`toAgentId`	string	The agent it is waiting for.
`body`	string	What the sender wrote.
`replyTo`	string	The mail this one answers, unset when it opens a subject.
`createdAt`	string	When it was sent, in RFC 3339.
`claimedAt`	string	When the recipient took it, unset while it is still waiting.
`expiresAt`	string	When it stops being offered, whether or not it was ever taken.
`kind`	MailKind	Whether an agent wrote it or komrad raised it.

MailDirection#

MailDirection is which half of an agent's correspondence a listing asks for.

Value	Description
`MAIL_DIRECTION_RECEIVED`	The mail addressed to the agent.
`MAIL_DIRECTION_SENT`	The mail the agent sent.

MailKind#

MailKind tells an agent's own mail from a notice komrad raised itself.

Value	Description
`MAIL_KIND_PLAIN`	One agent writing to another, or the person writing to an agent.
`MAIL_KIND_REVIEW_ACTIVITY`	Komrad saying a review has moved, naming the file the comments were written to.
`MAIL_KIND_EXCHANGE_CAPPED`	Komrad telling an agent that it and one other have spent their mail limit.