Skip to main content
Every IMAP folder becomes a folder of days, with one JSON file per message and a folder of its attachments. Sending goes through SMTP with the himalaya CLI.

Setup

The mailbox needs password-authenticated IMAP (reading) and SMTP (sending). Most providers want an app password instead of the account password.
Microsoft 365 is unsupported: it requires OAuth for IMAP, and the Email VFS accepts only passwords.
Yahoo: open Account Security, select Create app password under External connections, name it (for example Mirage), select Generate password and copy it.Fastmail: open Settings, Privacy & Security, then Manage app passwords and access and New app password. Keep the Mail, Contacts & Calendars access, select Generate password and copy it. Fastmail Basic plans have no IMAP or SMTP access.iCloud: sign in at account.apple.com, open Sign-In and Security, App-Specific Passwords, select Generate an app-specific password and copy it. The Apple Account needs two-factor authentication.ProtonMail: run Proton Mail Bridge locally and use the credentials it shows.Self-hosted or other: use the mail account’s password, or whatever the server requires.

Connect

workspace.yaml

Layout

  • A folder keeps its IMAP name; a day comes from the message’s Date header.
  • A message file is <subject>__<uid>.email.json with a sanitized subject, so ls the day rather than build the name.
  • Each folder lists its newest 200 messages; max_messages changes that.

Sample runs

The mount is read-only. Send, reply and forward with the himalaya CLI, which uses the SMTP settings.

Troubleshooting

  • Authentication failed: check that the provider accepts passwords for IMAP and SMTP, and whether it requires an app password.
  • Connection refused: check the host and port; some networks block 993 or 587. For ProtonMail, make sure Bridge is running.
  • SSL handshake failed: check the host and the implicit-TLS IMAP port (commonly 993). use_ssl: false opens a plain connection with no STARTTLS upgrade.

SDK guides

Python

Every config field, the VFS.md and write support.

TypeScript

Every config field, the VFS.md and write support.