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

The 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

float
default:"30"
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.
str
required
IMAP server hostname.
int
default:"993"
IMAP server port.
str
required
SMTP server hostname himalaya sends mail through.
int
default:"587"
SMTP server port. 465 uses implicit TLS; any other port starts in plaintext and upgrades with STARTTLS when the server offers it.
str
required
Login for both IMAP and SMTP, usually the email address.
str
required
secret
Password or app password for username.
bool
default:"True"
Speak TLS from the first byte of the IMAP connection (IMAPS); off connects in plaintext. SMTP follows smtp_port instead.
int
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.
bool
default:"True"
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.
str
Mailbox a sent copy goes to. Unset asks the server for the mailbox tagged \Sent and falls back to Sent.
str
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 max_messages messages (200).
  • TLS: IMAP speaks TLS from the first byte (IMAPS) by default. use_ssl=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 max_messages 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.