> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Email

> Virtualize an IMAP mailbox from Node.

`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`](https://docs.mirage.strukto.ai/typescript/cli/himalaya) CLI sends mail over SMTP. Set up the credentials as in [Email setup](https://docs.mirage.strukto.ai/home/setup/email.md).

## Install

```bash theme={null}
npm install @struktoai/mirage-node imapflow mailparser nodemailer
```

`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

```ts theme={null}
import { EmailVFS, MountMode, Workspace } from '@struktoai/mirage-node'

const email = new EmailVFS({
  imapHost: process.env.IMAP_HOST!,
  smtpHost: process.env.SMTP_HOST!,
  username: process.env.EMAIL_USERNAME!,
  password: process.env.EMAIL_PASSWORD!,
})
const ws = new Workspace({ '/email': email }, { mode: MountMode.READ })

const result = await ws.shell('ls /email && rg -l quarterly /email/INBOX')
console.log(result.stdoutText)
await ws.close()
```

`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

**timeout** `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.

**imapHost** `string` *required*

IMAP server hostname.

**imapPort** `number` (default: 993)

IMAP server port.

**smtpHost** `string` *required*

SMTP server hostname `himalaya` sends mail through.

**smtpPort** `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.

**username** `string` *required*

Login for both IMAP and SMTP, usually the email address.

**password** `string` *required*

Password or app password for `username`.

**useSsl** `boolean` (default: true)

Speak TLS from the first byte of the IMAP connection (IMAPS); off connects in plaintext. SMTP follows `smtpPort` instead.

**maxMessages** `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.

**saveCopy** `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.

**sentFolder** `string` (default: null)

Mailbox a sent copy goes to. Unset asks the server for the mailbox tagged `\Sent` and falls back to `Sent`.

**trashFolder** `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.

| Provider | IMAP host | SMTP host | Notes |
| - | - | - | - |
| Yahoo | `imap.mail.yahoo.com` | `smtp.mail.yahoo.com` | App password |
| Fastmail | `imap.fastmail.com` | `smtp.fastmail.com` | App password |
| iCloud | `imap.mail.me.com` | `smtp.mail.me.com` | App password |
| ProtonMail | `127.0.0.1` | `127.0.0.1` | Proton Mail Bridge |
| Self-hosted | the server's hostname | the server's hostname | The server's own login |

## Layout

```text theme={null}
/email/
  INBOX/
    2026-11-16/
      Meeting_Notes__12345.email.json
      Meeting_Notes__12345/
        report.pdf
        screenshot.png
  Sent/
    2026-11-16/
      ...
```

* **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`](https://docs.mirage.strukto.ai/typescript/cli/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](https://docs.mirage.strukto.ai/home/integration/overview.md).

* `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](https://docs.mirage.strukto.ai/home/limits.md#command-output) reads every file instead.

## VFS.md

The [VFS.md](https://docs.mirage.strukto.ai/home/setup/vfs-md.md) an agent reads with Email mounted at `/<path>`.

> [tab] Rendered
>
> **Virtual Filesystem**
>
> | Path | Description |
> | - | - |
> | `/<path>` | `email`, read |
>
> **VFS Layout**
>
> **`/<path>`**
>
> ```text theme={null}
> /<path>
>   <folder>/                         # INBOX, Sent, Drafts, ...
>     <yyyy-mm-dd>/
>       <subject>__<uid>.email.json   # the message as JSON
>       <subject>__<uid>/             # its attachments, if any
>         <attachment-filename>
> ```
>
> * `<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 VFS**
>
> Unix commands work on each path as on a local filesystem, as far as the path supports them:
>
> | Path | Supported |
> | - | - |
> | `/<path>` | Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest). `grep -r` and `rg` ask `email` which files may match. |
>
> **Limitations of Unix Commands for VFS**
>
> Where a path differs from a local filesystem:
>
> | Path | Limitations |
> | - | - |
> | `/<path>` | Read only: no command changes files. `email` answers only for `*/*/*.email.json`; `grep -r` and `rg` read every other file. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |
>
> Run `man <cmd>` or `<cmd> --help` for one command's usage.

> [tab] Raw
>
> ````markdown theme={null}
> ---
> name: workspace-filesystem
> description: The virtual filesystem layout of this workspace.
> ---
>
> # Virtual Filesystem
>
> | Path | Description |
> | --- | --- |
> | `/<path>` | `email`, read |
>
> ## VFS Layout
>
> ### `/<path>`
>
> ```text
> /<path>
>   <folder>/                         # INBOX, Sent, Drafts, ...
>     <yyyy-mm-dd>/
>       <subject>__<uid>.email.json   # the message as JSON
>       <subject>__<uid>/             # its attachments, if any
>         <attachment-filename>
> ```
>
> - `<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 VFS
>
> Unix commands work on each path as on a local filesystem, as far as the path supports them:
>
> | Path | Supported |
> | --- | --- |
> | `/<path>` | Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest). `grep -r` and `rg` ask `email` which files may match. |
>
> ## Limitations of Unix Commands for VFS
>
> Where a path differs from a local filesystem:
>
> | Path | Limitations |
> | --- | --- |
> | `/<path>` | Read only: no command changes files. `email` answers only for `*/*/*.email.json`; `grep -r` and `rg` read every other file. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |
>
> Run `man <cmd>` or `<cmd> --help` for one command's usage.
> ````


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.