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
email extra is for sending through himalaya; reading needs no extra.
Configure
imap_port (993) and smtp_port (587) change the ports, and max_messages
how many messages each folder lists. save_copy, sent_folder and
trash_folder 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
smtp_port 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 sent_folder, 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
max_messagesmessages (200). - TLS: IMAP speaks TLS from the first byte (IMAPS) by default.
use_ssl=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 thanmax_messagesmessages 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.