> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Email

> An agent answers email with context scattered across the inbox, chat and shared files, and never sends a reply until a person approves it. Mirage sets up a managed virtual terminal for the task.

![mirage](https://docs.mirage.strukto.ai/logo/light.svg)
![mirage](https://docs.mirage.strukto.ai/logo/dark.svg)

An email agent reads what lands in an inbox, finds what it needs to answer,
and drafts the reply. The answer is rarely in the email itself. It sits in a
chat thread or a file someone shared, often with more in it than the reply
should carry. The agent drafts, and a person decides what is sent.

Email is reads and writes over scattered context, an inbox, chat and the
files shared in it, and that is the work Mirage is built for. The agent
reaches all of it from one terminal, with fewer tokens than calling the
same services as MCP tools
([VFS-Bench 1.0](https://agentvfs.org/benchmark/vfs-bench-1)). Its limits
are fixed, one inbox to answer from and nothing sent without a person, and
a managed terminal holds an agent to exactly that. Here it runs as an
[in-process terminal](https://docs.mirage.strukto.ai/home/examples/in-process-terminal.md) on a Mirage
server, without a VM or sandbox.

## Setup

> [card] Mail
>
> [`himalaya`](https://docs.mirage.strukto.ai/python/cli/himalaya), an email CLI, reads the inbox, saves drafts and sends.

> [card] Files
>
> [Slack](https://docs.mirage.strukto.ai/python/vfs/slack.md) is mounted read-only at `/slack`, files included.

> [card] Policy
>
> A policy script, `guard.py`, checks every reply and holds each send for a person.

You need the `mirage` CLI, a Slack bot, a mailbox and two keys,
`SLACK_BOT_TOKEN` and `MAIL_PASSWORD`.

> [accordion] Slack and a mailbox
>
> **Slack.** A bot with `channels:read`, `channels:history` and `files:read`,
> plus `groups:read` and `groups:history` for a private channel. See
> [Slack](https://docs.mirage.strukto.ai/home/setup/slack.md). Invite it to `#incidents`, and post the note
> above with the CSV as a message in the channel, not as a reply in a
> thread: the mount shows a channel's messages, not its threads.
>
> **Mail.** Any IMAP and SMTP account works; see [Email](https://docs.mirage.strukto.ai/home/setup/email.md).
> To try the example without one, run [GreenMail](https://greenmail-mail-test.github.io/greenmail/),
> a mail server for tests, in Docker. It takes any password and keeps every
> message on your machine, so nothing reaches a real inbox:
>
> ```bash theme={null}
> docker run -d --name greenmail -p 3025:3025 -p 3143:3143 greenmail/standalone:2.1.15
> ```
>
> A real mailbox comes with `Drafts` and `Sent` folders. GreenMail starts with
> none, so create them:
>
> ```bash theme={null}
> curl -s imap://localhost:3143 -u support@acme.example:any -X 'CREATE Drafts'
> curl -s imap://localhost:3143 -u support@acme.example:any -X 'CREATE Sent'
> ```
>
> Then send the customer's email to the support address:
>
> ```bash theme={null}
> curl -s smtp://localhost:3025 -T - \
>   --mail-from priya@northwind.example --mail-rcpt support@acme.example <<EOF
> From: Priya Shah <priya@northwind.example>
> To: support@acme.example
> Date: $(date -u -R)
> Message-ID: <calendar-sync-1@northwind.example>
> Subject: Our calendar sync failed this morning
>
> Hi, appointments were missing from our calendars this morning.
> What happened, did we lose any data, and which appointments were
> affected? Our clinics want to check them with patients.
>
> Priya
> EOF
> ```
>
> `MAIL_PASSWORD` can be anything for GreenMail.

> [accordion] Installation
>
> The policy runs on [Monty](https://docs.mirage.strukto.ai/home/policy/scripts.md#runtimes), a small sandboxed
> Python interpreter:
>
> > [tab] pip
> >
> > ```bash theme={null}
> > pip install 'mirage-ai[email,monty]'
> > ```
>
> > [tab] npm
> >
> > ```bash theme={null}
> > npm install -g @struktoai/mirage-cli @pydantic/monty
> > ```

> [accordion] workspace.yaml
>
> `workspace.yaml` mounts Slack read-only, keeps `/workspace` in memory and
> installs `himalaya` with the support account. With your own mailbox, set its
> hosts and username, and drop the two ports and `use_ssl`.
>
> The `support` profile is what every terminal gets. Its allow list leaves
> the agent the text tools it needs and three mail commands, to list, read
> and reply: no `compose`, `forward`, `delete` or raw `send`. Its policy,
> `guard.py`, judges each reply before it runs:
>
> ```yaml workspace.yaml theme={null}
> mounts:
>   /slack:
>     vfs: slack
>     mode: read
>     config:
>       token: {from: env, key: SLACK_BOT_TOKEN}
>   /workspace:
>     vfs: ram
>     mode: write
>
> clis:
>   himalaya:
>     cli: himalaya
>     machine: in_process
>     config:
>       imap_host: localhost
>       imap_port: 3143
>       smtp_host: localhost
>       smtp_port: 3025
>       use_ssl: false
>       username: support@acme.example
>       password: {from: env, key: MAIL_PASSWORD}
>
> profiles:
>   support:
>     commands:
>       allow: [cd, pwd, echo, cat, ls, grep, jq, head, tail, wc, awk, cut, sort, uniq, mkdir,
>               himalaya envelope list, himalaya message read, himalaya message reply]
>     policy:
>       pre_command:
>         - {script: ./guard.py}
>
> profile: support
> ```

> [accordion] guard.py
>
> `guard.py` sees each command after the shell has expanded it, so a variable
> or a glob cannot hide a recipient or a path. It judges only
> `himalaya message reply`, the one way the profile lets the agent write
> mail, with one rule per function:
>
> * `hides_a_flag_value`: a flag must be written apart from its value, as
>   `--attach FILE`, not `--attach=FILE` or `-tADDR`, so the rules below see
>   every value.
> * `adds_a_recipient`: a reply goes to whoever wrote in, and no one else, so
>   `--to`, `--cc` and `--bcc` are refused.
> * `attaches_a_bad_report`: an attachment must be a report the agent built
>   in `/workspace/outbox/`, never a file straight from Slack, and
>   `customers_in` reads its first column to check that it holds one
>   customer.
> * `sends_now`: `--send` asks a person. Without it, a reply is only saved
>   to `Drafts`.
>
> ```python guard.py theme={null}
> OUTBOX = "/workspace/outbox/"
> RECIPIENT_FLAGS = ("-t", "--to", "--cc", "--bcc")
>
>
> def is_reply(words):
>     return [w["text"] for w in words[:3]] == ["himalaya", "message", "reply"]
>
>
> def hides_a_flag_value(words):
>     for w in words:
>         t = w["text"]
>         if w["kind"] == "option" and ("=" in t or (not t.startswith("--") and len(t) > 2)):
>             return "write each flag and its value apart"
>
>
> def adds_a_recipient(words):
>     for w in words:
>         if w["text"] in RECIPIENT_FLAGS:
>             return "a reply goes only to the sender"
>
>
> def customers_in(report):
>     names = []
>     for line in open(report).read().splitlines()[1:]:
>         name = line.split(",")[0]
>         if line and name not in names:
>             names.append(name)
>     return names
>
>
> def attaches_a_bad_report(words):
>     for w in words:
>         if w["option"] != "--attach":
>             continue
>         report = w["path"] or ""
>         if not report.startswith(OUTBOX):
>             return "attach only reports from " + OUTBOX
>         if len(customers_in(report)) != 1:
>             return "a report holds one customer's data"
>
>
> def sends_now(words):
>     return "--send" in [w["text"] for w in words]
>
>
> def pre_command(ctx):
>     words = ctx["words"]
>     if not is_reply(words):
>         return None
>     problem = hides_a_flag_value(words) or adds_a_recipient(words) or attaches_a_bad_report(words)
>     if problem:
>         return {"kind": "deny", "reason": problem}
>     if sends_now(words):
>         return {"kind": "ask", "reason": "a person approves every send"}
>     return None
> ```

Export the keys, create the workspace, and open a terminal for the agent:

```bash theme={null}
export SLACK_BOT_TOKEN=xoxb-... MAIL_PASSWORD=any
mirage daemon restart
mirage workspace create workspace.yaml --id support
export MIRAGE_WORKSPACE=support
mirage workspace session create -s agent
```

The local server reads the keys when it starts, so `mirage daemon restart`
stops a server that started without them.

## Example

A customer emails the support inbox about a calendar sync failure the team
already dealt with, and asks which of their appointments it hit. The answer
is in Slack, where an engineer posted this in the `#incidents` channel with
a CSV of every customer's affected events:

> **Incident 2026-11-16:** calendar sync failed 06:10–07:40 UTC for Northwind Health, Harbor Dental and Lakeside Physio.\
>
> **Cause:** an expired Google token on our side; no data was lost.\
>
> **Fix:** token rotated, sync re-run for the window, every affected event is back.\
>
> Affected events for all three customers attached. Share each customer only their own.\
>
> 📎 `affected-events.csv`

The CSV has one row per event, with the customer first:

| customer | clinic | event\_id | starts\_at |
| - | - | - | - |
| Harbor Dental | Ballard | evt\_4101 | 2026-11-16T08:15:00Z |
| Northwind Health | Tacoma | evt\_4102 | 2026-11-16T08:45:00Z |
| … | | | |

These are the commands the agent runs, in the `agent` terminal Setup
created. Your agent sends each one with `mirage shell -s agent`, or through [MCP](https://docs.mirage.strukto.ai/home/access/mcp.md), the
[HTTP API](https://docs.mirage.strukto.ai/home/access/http.md), [RPC](https://docs.mirage.strukto.ai/home/access/rpc.md) or [SSH](https://docs.mirage.strukto.ai/home/access/ssh.md).

**1. Read the email**

The new email is message 1 in the inbox.

```bash theme={null}
himalaya message read 1
```

Priya Shah, at Northwind Health, asks which appointments the sync failure hit.

**2. Find the note in Slack**

A Slack channel is a folder under `/slack`, with the day's messages and the files shared that day.

```bash theme={null}
grep "calendar sync" /slack/channels/incidents__*/2026-11-16/chat.jsonl
```

The engineer's note. The agent keeps the attached CSV's path as `$events`.

**3. Keep only this customer's rows**

The agent copies the CSV's header and Northwind Health's rows into a report, `$report`, in `/workspace/outbox/`.

```bash theme={null}
grep "^Northwind Health," "$events" >> "$report"
```

214 appointments: 77 at Bellevue, 75 at Tacoma and 62 at Everett.

**4. Save the reply as a draft**

The agent writes the reply to `/workspace/reply.txt`, then saves it with the report attached.

```bash theme={null}
himalaya message reply 1 --body-file /workspace/reply.txt --attach "$report" --save Drafts
```

The draft waits in `Drafts`. Nothing has been sent.

**5. Mistakes are refused**

If the agent copies someone in, attaches the raw CSV, or deletes mail, the command is refused before it runs. Each prints `himalaya: Permission denied` and the reason:

| The agent runs | Reason |
| - | - |
| `himalaya message reply 1 --save Drafts --cc ceo@other.example` | a reply goes only to the sender |
| `himalaya message reply 1 --save Drafts --attach "$events"` | attach only reports from /workspace/outbox/ |
| `himalaya message reply 1 --save Drafts --attach /workspace/outbox/all.csv`, a copy of the export | a report holds one customer's data |
| `himalaya message delete 1` | himalaya message delete is not allowed |

**6. Send once a person approves**

```mermaid theme={null}
sequenceDiagram
    participant A as Agent
    participant M as Mirage
    participant P as Person
    A->>M: himalaya message reply 1 … --send
    M-->>A: requires approval (ask 316ec6bc7e20)
    P->>M: mirage workspace allow support 316ec6bc7e20
    A->>M: the same command again
    M-->>A: Message successfully saved and sent
```

A person approves from their own terminal, with the ask ID the refusal printed, and the same command then sends:

```bash theme={null}
mirage workspace allow support 316ec6bc7e20
```

> [accordion] Full commands
>
> Each line runs in the agent's terminal with `mirage shell -s agent`, which
> keeps variables such as `$report` from one call to the next.
>
> ```bash theme={null}
> mirage shell -s agent -c 'himalaya envelope list'
> mirage shell -s agent -c 'himalaya message read 1'
> mirage shell -s agent -c 'grep -h "calendar sync" /slack/channels/incidents__*/2026-11-16/chat.jsonl | jq -r .text'
> mirage shell -s agent -c 'events=$(ls -d /slack/channels/incidents__*/2026-11-16/files/affected-events__*) && echo "$events"'
> mirage shell -s agent -c '
> mkdir -p /workspace/outbox
> report=/workspace/outbox/northwind-health-affected.csv
> head -1 "$events" > "$report"
> grep "^Northwind Health," "$events" >> "$report"
> tail -n +2 "$report" | wc -l
> tail -n +2 "$report" | cut -d, -f2 | sort | uniq -c'
> mirage shell -s agent -c 'cat > /workspace/reply.txt' <<'EOF'
> Hi Priya,
>
> This morning from 06:10 to 07:40 UTC, calendar sync stopped because a
> Google token on our side had expired. No data was lost: we rotated the
> token, re-ran the sync for that window, and every event is back.
>
> 214 of your appointments, from today to Friday, did not sync in that
> window: 77 at Bellevue, 75 at Tacoma and 62 at Everett. The attached CSV
> lists each one with its clinic, event ID and start time, so your clinics
> can check them with patients.
>
> Best,
> Acme Support
> EOF
> mirage shell -s agent -c 'himalaya message reply 1 --body-file /workspace/reply.txt --attach "$report" --save Drafts'
> mirage shell -s agent -c 'himalaya message reply 1 --save Drafts --cc ceo@other.example'
> mirage shell -s agent -c 'himalaya message reply 1 --save Drafts --attach "$events"'
> mirage shell -s agent -c 'cat "$events" > /workspace/outbox/all.csv && himalaya message reply 1 --save Drafts --attach /workspace/outbox/all.csv'
> mirage shell -s agent -c 'himalaya message delete 1'
> mirage shell -s agent -c 'himalaya message reply 1 --body-file /workspace/reply.txt --attach "$report" --send'
> mirage workspace list-asks
> mirage workspace allow support ASK_ID
> mirage shell -s agent -c 'himalaya message reply 1 --body-file /workspace/reply.txt --attach "$report" --send'
> ```

For the commands and flags `himalaya` supports, see
[himalaya](https://docs.mirage.strukto.ai/python/cli/himalaya.md). For more on asks, see
[Policies](https://docs.mirage.strukto.ai/home/policy/policies.md#asks) and [Scripts](https://docs.mirage.strukto.ai/home/policy/scripts.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.