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
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.
SMTP server port.
465 uses implicit TLS; any other port starts in plaintext and upgrades with STARTTLS when the server offers it.Speak TLS from the first byte of the IMAP connection (IMAPS); off connects in plaintext. SMTP follows
smtpPort instead.How many of a folder’s newest messages the mount lists and
grep searches, and the window himalaya envelope list and search page through.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.Mailbox a sent copy goes to. Unset asks the server for the mailbox tagged
\Sent and falls back to Sent.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.Authentication
The mount logs in to IMAP withusername 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-DDof theirDateheader. - Messages: each message is
<subject>__<uid>.email.json, with a sanitized subject, solsthe day rather than build the name. The UID after__is whathimalayatakes. - 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
himalayaCLI, which uses the SMTP settings, to list, read, send, reply and forward. - Newest messages: each folder lists its newest
maxMessagesmessages (200). - TLS: IMAP speaks TLS from the first byte (IMAPS) by default.
useSsl: falseconnects 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 -randrg: IMAPSEARCH TEXTnames 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 thanmaxMessagesmessages in a folder, or the search fails. A server that answersSEARCHfrom 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: -1in the mount’s"@all"command limit reads every file instead.
VFS.md
The VFS.md an agent reads with Email mounted at/<path>.
- Rendered
- Raw
Virtual Filesystem
VFS Layout
/<path><subject>is sanitized:lsthe date directory rather than construct it.- To list, search, read, compose, reply or forward, use the
himalayaCLI if installed (himalaya --help).
Limitations of Unix Commands for VFSWhere a path differs from a local filesystem:
Run
man <cmd> or <cmd> --help for one command’s usage.