komrad

list_mail

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

read-onlyidempotentMCP toolAgent

Set direction to list what the agent sent.

Calling it#

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

Request#

ListMailRequest#

FieldTypeDescription
iduuid

The agent whose mail to list, by id. Unset lists the caller's own.

paginationPagination

The page to read.

directionMailDirection

Whether to list the mail the agent received or sent.

Response#

ListMailResponse#

FieldTypeDescription
mailMail[]

One page of mail, newest first. Listing mail does not mark it read.

next_page_tokenstring

The cursor for the next page. Unset on the last page.

Types#

Pagination#

Pagination selects one page of a listing.

FieldTypeDescription
limitint32

at least 0

How many records to return. Komrad caps the value, and picks one when unset.

cursorstring

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.

FieldTypeDescription
iduuid*

The mail's id. Pass it as reply_to to answer.

from_agent_iduuid

The id of the agent that sent the mail. Unset when komrad sent it.

from_namestring

The sender's name. Mail komrad sent carries komrad's name.

to_agent_iduuid*

The id of the agent the mail is for.

bodystring

The mail's text.

reply_touuid

The id of the mail this one answers. Unset when the mail starts a thread.

created_attimestamp

When the mail was sent.

claimed_attimestamp

When the recipient read the mail. Unset while it is unread.

expires_attimestamp

When the mail expires, read or not.

kindMailKind

Who wrote the mail and why.

MailDirection#

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

ValueDescription
received

The mail sent to the agent.

sent

The mail the agent sent.

MailKind#

MailKind is who wrote a piece of mail and why.

ValueDescription
plain

Mail from an agent or the person.

review_activity

From komrad: a review changed. The mail names the review.

exchange_capped

From komrad: the agent and one other agent have used up their mail limit with each other.

document_edited

From komrad: the person wrote or edited one of the agent's documents.

pull_request_changed

From komrad: a pull request on the agent's branch changed on the forge.

worktree_rebased

From komrad: komrad rebased the agent's worktree, or tried to.

worktree_pushed

From komrad: the agent's branch was force-pushed to origin.

worktree_aborted

From komrad: the sequence stopped in the agent's worktree was aborted.

review_comment

From komrad: the person commented on the agent's work. The mail carries the comment.

agent_failed_to_start

From komrad: an agent this agent created exited as its CLI launched. The mail names the agent.

agent_turn_failed

From komrad: a turn of an agent this agent created ended on an error. The mail names the agent.

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

From komrad: komrad closed the agent's pane mid-turn to stay inside its memory limit, stopping every process the agent started.

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

From komrad: komrad deleted build output from the agent's worktree while its task was archived.