Skip to main content
EmailVFS mounts an IMAP mailbox as read-only files: each folder holds one folder per day of messages as JSON, with their attachments. The himalaya CLI sends mail over SMTP. Set up the credentials as in Email setup.

Install

imapflow, mailparser and nodemailer are peer packages. The class ships in @struktoai/mirage-node only: a browser cannot open the raw TCP connections IMAP and SMTP need.

Configure

imapPort (993) and smtpPort (587) change the ports, and maxMessages how many messages each folder lists. saveCopy, sentFolder and trashFolder shape what himalaya does after a send or delete.

Fields

number
default:"DEFAULT_TIMEOUT"
Seconds a request may wait to connect, or between two reads of its answer, before it fails; a download that keeps flowing is never cut off.
string
required
IMAP server hostname.
number
default:"993"
IMAP server port.
string
required
SMTP server hostname himalaya sends mail through.
number
default:"587"
SMTP server port. 465 uses implicit TLS; any other port starts in plaintext and upgrades with STARTTLS when the server offers it.
string
required
Login for both IMAP and SMTP, usually the email address.
string
required
secret
Password or app password for username.
boolean
default:"true"
Speak TLS from the first byte of the IMAP connection (IMAPS); off connects in plaintext. SMTP follows smtpPort instead.
number
default:"200"
How many of a folder’s newest messages the mount lists and grep searches, and the window himalaya envelope list and search page through.
boolean
default:"true"
After himalaya sends a message, append a copy to sentFolder, as upstream himalaya’s message.send.save-copy. Off saves a copy only when --save names a mailbox.
string
default:"null"
Mailbox a sent copy goes to. Unset asks the server for the mailbox tagged \Sent and falls back to Sent.
string
default:"null"
Mailbox himalaya message delete moves messages to, as upstream’s mailbox.alias.trash. Unset asks the server for the mailbox tagged \Trash and falls back to Trash.
Fields marked secret are redacted in snapshots.

Authentication

The mount logs in to IMAP with username and password; sending through himalaya uses the same pair on SMTP. Most providers want an app password instead of the account password. Microsoft 365 is unsupported: it requires OAuth for IMAP, and the mount accepts only passwords.

Layout

  • Folders: the root lists the IMAP folders under their own names (INBOX, Sent, Drafts).
  • Days: inside a folder, messages are grouped by the YYYY-MM-DD of their Date header.
  • Messages: each message is <subject>__<uid>.email.json, with a sanitized subject, so ls the day rather than build the name. The UID after __ is what himalaya takes.
  • Attachments: a message with attachments gets a folder of the same base name holding them.

Behavior

  • Read only: the mount cannot send or change mail. Use the himalaya CLI, which uses the SMTP settings, to list, read, send, reply and forward.
  • Newest messages: each folder lists its newest maxMessages messages (200).
  • TLS: IMAP speaks TLS from the first byte (IMAPS) by default. useSsl: false connects in plaintext with no STARTTLS upgrade. SMTP follows its port.

Integration

The IMAP server answers this command, so fewer messages are read. See Integration.
  • grep -r and rg: IMAP SEARCH TEXT names the messages to read in each folder or day they walk (from the mount root, in every folder), and the output matches reading every message. IMAP matches headers and body in any case. Attachments are always read. Every message is read when the text is a key of the message JSON or a flag name, holds anything but ASCII letters and spaces, matches more than maxMessages messages in a folder, or the search fails. A server that answers SEARCH from a full-text index (Dovecot with an FTS plugin, for one) matches words rather than substrings, so a narrowed scan can miss a message there; walk_limit: -1 in the mount’s "@all" command limit reads every file instead.

VFS.md

The VFS.md an agent reads with Email mounted at /<path>.
Virtual FilesystemVFS Layout/<path>
  • <subject> is sanitized: ls the date directory rather than construct it.
  • To list, search, read, compose, reply or forward, use the himalaya CLI if installed (himalaya --help).
Supported Unix Commands for VFSUnix commands work on each path as on a local filesystem, as far as the path supports them:Limitations of Unix Commands for VFSWhere a path differs from a local filesystem:Run man <cmd> or <cmd> --help for one command’s usage.