Himalaya

List and search IMAP mail, read messages, and compose, reply, forward or send through SMTP. Mirage uses the Himalaya command vocabulary with JSON output and workspace file attachments.

Setup

Configure the account using Email setup. Python needs the email extra; TypeScript imports HIMALAYA from the Node package.

from mirage import Workspace
from mirage.commands.cli.builtin.himalaya import HIMALAYA
from mirage.core.email.config import EmailConfig

config = EmailConfig(
    imap_host="imap.example.com",
    smtp_host="smtp.example.com",
    username="agent@example.com",
    password="app-password",
)
ws = Workspace({})
ws.register_cli("himalaya", HIMALAYA, config)

No service mount is required. For YAML and multiple accounts, see the CLI overview.

Supported commands

Run himalaya <command> --help for the supported flags and operands. This list is generated from Mirage’s registered command tree.

Command	Description
`himalaya envelope list`	List envelopes as JSON headers. Aliases: `ls`.
`himalaya envelope search`	Search envelopes with the query DSL. Aliases: `sr`.
`himalaya message read`	Read one message as JSON
`himalaya message compose`	Compose a new message from flags. Aliases: `write`, `new`.
`himalaya message send`	Send a raw RFC 5322 message
`himalaya message reply`	Reply to a message
`himalaya message forward`	Forward a message. Aliases: `fwd`.

Triage and read

himalaya envelope list -m INBOX --page 1 --page-size 10
himalaya envelope search -m INBOX not flag seen and from alice@example.com
himalaya envelope search after 2026-01-01 order by subject asc
himalaya envelope search subject '"quarterly review"'
himalaya message read -m INBOX 12345
himalaya message read -m INBOX 12345 --raw

Messages take positional IDs. -m/--mailbox defaults to INBOX. Envelopes include headers, identifiers, flags and attachment metadata; bodies and snippets appear in message read. --raw returns RFC 5322 bytes. Listings are newest first, with pages starting at 1 and a default page size of 25. The account’s max_messages (default 200) bounds the search and paging window. Sorted search considers that whole window. Search conditions are date, before, after, from, to, subject, body and flag. Combine them with and, or, not and parentheses; sort with order by date|from|to|subject [asc|desc]. Date conditions use the message’s Date: header, and after is exclusive. A pattern containing spaces needs literal double quotes inside the shell quotes, as above. Malformed queries exit 1 before contacting the server.

Compose, reply and send

himalaya message compose --to you@example.org --subject Report --body 'See attached' --attach /work/report.pdf
himalaya message compose --to you@example.org --subject Hello --body Hi --send
echo 'The body' | himalaya message compose --to you@example.org --subject Hello | himalaya message send
himalaya message reply -m INBOX 12345 --body 'Thanks' --send
himalaya message forward -m INBOX 12345 --to colleague@example.com --send

Without --send, compose/reply/forward print MIME bytes and send nothing. Bodies come from --body or stdin. message send accepts raw MIME on stdin or as its inline operand. --attach is repeatable and reads workspace files through the VFS; --from, --to, --cc, --bcc, --subject and --signature control the composed message. Reply uses Reply-To or From, adds reply headers and quotes the source. Forward prefixes the subject with Fwd: and keeps References. Both accept --posting-style top|bottom and --quote-headline. There is no reply-all switch; supply the extra recipients through --cc.

Save drafts and sent copies

himalaya message compose --to you@example.org --body Draft --save Drafts
himalaya message send --save Sent < /work/message.eml

Sending normally saves a seen copy by IMAP after SMTP succeeds. Mirage uses the server’s \Sent folder, or the config’s sent_folder (sentFolder) when set. save_copy=False (saveCopy: false) disables the default copy. --save MAILBOX overrides both settings for one command; without --send on a composer, it saves a draft and sends nothing. A sent-copy failure after delivery is a warning with exit 0: retrying would send the message twice. Saving a draft without sending fails normally if IMAP refuses it.

VFS and limits

The optional Email VFS exposes the mailbox as files. Reading a message does not mark it seen. The CLI uses its own account config; attachments can come from any readable workspace mount. Mailbox management, moving/deleting messages, flag mutation and attachment download commands are absent. --body-file and --signature-file are also absent; use stdin. Output is JSON rather than upstream’s tables, and sent-copy saving defaults on in Mirage. Server matching rules still determine how search patterns match addresses and text. Upstream Himalaya offers a choice of MIT or Apache-2.0. Mirage’s command implementation is Apache-2.0; see compatibility and licenses.

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Setup

Supported commands

Triage and read

Compose, reply and send

Save drafts and sent copies

VFS and limits

​Setup

​Supported commands

​Triage and read

​Compose, reply and send

​Save drafts and sent copies

​VFS and limits

Setup

Supported commands

Triage and read

Compose, reply and send

Save drafts and sent copies

VFS and limits