# imapflow

> IMAP Client for Node

Latest version **2.0.5** (published 2026-09-15) · MIT license · 0 weekly downloads

## Install

```sh
npm install imapflow
pnpm add imapflow
yarn add imapflow
bun add imapflow
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.0.5 |
| Published | 2026-09-15 |
| First published | 2019-12-19 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=20.0.0 |
| Dependencies | 8 |
| Unpacked size | 1.5 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 568 |
| Author | Postal Systems OÜ |
| Maintainers | andris |
| Keywords | imap, email, mail |

## Links

- npm: https://www.npmjs.com/package/imapflow
- Repository: https://github.com/postalsys/imapflow
- Homepage: https://imapflow.com/
- Issues: https://github.com/postalsys/imapflow/issues
- npm.io page: https://npm.io/package/imapflow

## Dependencies (8)

- [pino](https://npm.io/package/pino.md) 10.3.1
- [libqp](https://npm.io/package/libqp.md) 2.1.1
- [socks](https://npm.io/package/socks.md) 2.8.10
- [libmime](https://npm.io/package/libmime.md) 5.4.4
- [libbase64](https://npm.io/package/libbase64.md) 1.3.0
- [iconv-lite](https://npm.io/package/iconv-lite.md) 0.7.3
- [encoding-japanese](https://npm.io/package/encoding-japanese.md) 2.4.0
- [@zone-eu/mailsplit](https://npm.io/package/@zone-eu/mailsplit.md) 5.4.17

## Alternatives

- [@expo/fingerprint](https://npm.io/package/@expo/fingerprint.md) — 6.2M weekly downloads
- [@azure/monitor-opentelemetry-exporter](https://npm.io/package/@azure/monitor-opentelemetry-exporter.md) — 850.0K weekly downloads
- [@azure/monitor-opentelemetry](https://npm.io/package/@azure/monitor-opentelemetry.md) — 624.0K weekly downloads
- [@posthog/ai](https://npm.io/package/@posthog/ai.md) — 423.3K weekly downloads
- [fakefilter](https://npm.io/package/fakefilter.md) — 63.9K weekly downloads

## Recent versions

- 2.0.5 (latest) — 2026-09-15
- 2.0.4 — 2026-09-15
- 2.0.3 — 2026-09-14
- 2.0.2 — 2026-09-10
- 2.0.1 — 2026-09-10
- 2.0.0 — 2026-09-07
- 1.7.8 — 2026-09-01
- 1.7.7 — 2026-08-31
- 1.7.6 — 2026-08-24
- 1.7.5 — 2026-08-24
- 1.7.4 — 2026-08-24
- 1.7.3 — 2026-08-24
- 1.7.2 — 2026-08-21
- 1.7.1 — 2026-08-14
- 1.7.0 — 2026-08-12
- … 240 more at https://npm.io/package/imapflow/versions

## README

# ImapFlow

Modern and easy-to-use IMAP client library for Node.js.

[![npm](https://img.shields.io/npm/v/imapflow)](https://www.npmjs.com/package/imapflow)
[![license](https://img.shields.io/npm/l/imapflow)](https://github.com/postalsys/imapflow/blob/master/LICENSE)

ImapFlow provides a clean, promise-based API for working with IMAP, so you don't need in-depth knowledge of the protocol. IMAP extensions are detected and handled automatically. You write the same code regardless of server capabilities, and ImapFlow adapts behind the scenes. ImapFlow is the IMAP engine that powers [EmailEngine](https://emailengine.app/?utm_source=imapflow-readme&utm_medium=readme&utm_campaign=oss-docs&utm_content=intro), a self-hosted email API built by the same team.

## Features

- **Async/await API** - all methods return Promises
- **Automatic IMAP extension handling** - CONDSTORE, QRESYNC, IDLE, COMPRESS, and [more](https://imapflow.com/docs/)
- **Message streaming** - async iterators for efficient processing
- **Mailbox locking** - built-in locking mechanism for safe concurrent access
- **TypeScript support** - written in TypeScript, type definitions included
- **ES modules and CommonJS** - `import { ImapFlow } from 'imapflow'` and `const { ImapFlow } = require('imapflow')` both work
- **Proxy support** - SOCKS and HTTP CONNECT proxies
- **Gmail support** - labels, raw search via X-GM-EXT-1

## Installation

```bash
npm install imapflow
```

ImapFlow requires Node.js 20 or newer. The package ships both an ES module build and a CommonJS build with bundled type declarations, so no separate `@types` package is needed.

The ES module build also runs on [Bun](https://bun.sh/) (tested against the latest release) and on [Cloudflare Workers](https://developers.cloudflare.com/workers/) with the `nodejs_compat` compatibility flag. On Workers connect with implicit TLS (`secure: true`, usually port 993) or in cleartext: the runtime can not upgrade an already connected socket, so a STARTTLS negotiation fails with a TLS error, and it does not allow turning certificate validation off, so `tls: { rejectUnauthorized: false }` is rejected with `ERR_OPTION_NOT_IMPLEMENTED`. COMPRESS=DEFLATE, IDLE and the default pino logger work as on Node.js.

## Quick Example

```js
import { ImapFlow } from 'imapflow';
// or in CommonJS: const { ImapFlow } = require('imapflow');

const client = new ImapFlow({
    host: 'imap.example.com',
    port: 993,
    secure: true,
    auth: {
        user: 'user@example.com',
        pass: 'password'
    }
});

const main = async () => {
    await client.connect();

    let lock = await client.getMailboxLock('INBOX');
    try {
        // fetch latest message
        let message = await client.fetchOne(client.mailbox.exists, { source: true });
        console.log(message.source.toString());

        // list subjects for all messages
        for await (let message of client.fetch('1:*', { envelope: true })) {
            console.log(`${message.uid}: ${message.envelope.subject}`);
        }
    } finally {
        // always release the lock
        lock.release();
    }

    await client.logout();
};

main().catch(console.error);
```

See the [Quick Start guide](https://imapflow.com/docs/getting-started/quick-start) for more examples, including Gmail, Outlook, and Yahoo configuration.

## Documentation

Full documentation is available at **[imapflow.com](https://imapflow.com/docs/)**.

- [Installation](https://imapflow.com/docs/getting-started/installation) - requirements and setup
- [Quick Start](https://imapflow.com/docs/getting-started/quick-start) - your first ImapFlow application
- [Basic Usage](https://imapflow.com/docs/guides/basic-usage) - core concepts and patterns
- [Configuration](https://imapflow.com/docs/guides/configuration) - connection options and settings
- [Fetching Messages](https://imapflow.com/docs/guides/fetching-messages) - reading email data
- [Searching](https://imapflow.com/docs/guides/searching) - finding messages with search queries
- [Mailbox Management](https://imapflow.com/docs/guides/mailbox-management) - creating, renaming, and deleting mailboxes
- [API Reference](https://imapflow.com/docs/api/imapflow-client) - complete method and event documentation

> ImapFlow was built for **[EmailEngine](https://emailengine.app/?utm_source=imapflow-readme&utm_medium=readme&utm_campaign=oss-docs&utm_content=note)**, a self-hosted email API that turns Gmail, Microsoft 365, and IMAP accounts into REST endpoints, with managed OAuth2 and webhooks for incoming mail. If you need a production email integration rather than an IMAP client, start there.

## License

Copyright (c) 2020-2025 Postal Systems OU

Licensed under the MIT license.

---
_Source: https://npm.io/package/imapflow · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._