# send\_mail

Send mail to another agent by `to_agent_id` or `to_agent_name`, setting `reply_to` when answering.

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

Komrad refuses a name used in more than one workflow. A reviewer may mail only the agents on its task and its workflow's orchestrator.

## Calling it

```bash
curl -X POST http://127.0.0.1:8787/komrad.agent.v1.AgentService/SendMail \
  -H 'Content-Type: application/json' \
  -d '{
  "to_agent_id": "<to_agent_id>",
  "body": "<body>"
}'
```

```bash
komrad rpc send-mail \
  --to-agent-id '<uuid>' \
  --body '<string>'
```

```json
{
  "name": "send_mail",
  "arguments": {
    "to_agent_id": "<to_agent_id>",
    "body": "<body>"
  }
}
```

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

## Request

### SendMailRequest

| Field | Type | Description |
| --- | --- | --- |
| [one of](https://komrad.dev/latest/api/agent/send-mail.md#komrad-agent-v1-SendMailRequest-to)\* |  | The agent to send to. |
| [`to_agent_id`](https://komrad.dev/latest/api/agent/send-mail.md#komrad-agent-v1-SendMailRequest-to_agent_id) | uuid | The agent, by id. |
| [`to_agent_name`](https://komrad.dev/latest/api/agent/send-mail.md#komrad-agent-v1-SendMailRequest-to_agent_name) | string not empty | The agent, by the name of a live agent. |
| [`body`](https://komrad.dev/latest/api/agent/send-mail.md#komrad-agent-v1-SendMailRequest-body) | string\* at most 10000 characters | The mail's text. |
| [`reply_to`](https://komrad.dev/latest/api/agent/send-mail.md#komrad-agent-v1-SendMailRequest-reply_to) | uuid | The id of the mail this one answers, so the two read as a thread. |

## Response

### SendMailResponse

| Field | Type | Description |
| --- | --- | --- |
| [`mail`](https://komrad.dev/latest/api/agent/send-mail.md#komrad-agent-v1-SendMailResponse-mail) | [Mail](https://komrad.dev/latest/api/agent/send-mail.md#komrad-agent-v1-Mail) | The mail as sent. |
| [`warning`](https://komrad.dev/latest/api/agent/send-mail.md#komrad-agent-v1-SendMailResponse-warning) | string | Why the recipient will not read the mail soon. Unset when the recipient is running. |

## Types

### Mail

Mail is one message in an agent's mailbox.

| Field | Type | Description |
| --- | --- | --- |
| [`id`](https://komrad.dev/latest/api/agent/send-mail.md#komrad-agent-v1-Mail-id) | uuid\* | The mail's id. Pass it as [`reply_to`](https://komrad.dev/latest/api/agent/send-mail.md#komrad-agent-v1-Mail-reply_to) to answer. |
| [`from_agent_id`](https://komrad.dev/latest/api/agent/send-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/send-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/send-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/send-mail.md#komrad-agent-v1-Mail-body) | string | The mail's text. |
| [`reply_to`](https://komrad.dev/latest/api/agent/send-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/send-mail.md#komrad-agent-v1-Mail-created_at) | timestamp | When the mail was sent. |
| [`claimed_at`](https://komrad.dev/latest/api/agent/send-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/send-mail.md#komrad-agent-v1-Mail-expires_at) | timestamp | When the mail expires, read or not. |
| [`kind`](https://komrad.dev/latest/api/agent/send-mail.md#komrad-agent-v1-Mail-kind) | [MailKind](https://komrad.dev/latest/api/agent/send-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/send-mail.md#komrad-agent-v1-MailKind-plain) | Mail from an agent or the person. |
| [`review_activity`](https://komrad.dev/latest/api/agent/send-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/send-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/send-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/send-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/send-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/send-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/send-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/send-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/send-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/send-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/send-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/send-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/send-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/send-mail.md#komrad-agent-v1-MailKind-worktree_shrunk) | From komrad: komrad deleted build output from the agent's worktree while its task was archived. |
