imapflow

library1.3.2jsnpmunverified

ImapFlow is a modern, promise-based IMAP client library for Node.js, designed to simplify interactions with IMAP servers without requiring deep protocol knowledge. It provides an async/await API, automatically handles various IMAP extensions (like CONDSTORE, QRESYNC, IDLE, COMPRESS), and supports message streaming, mailbox locking, and proxy configurations. The current stable version is `1.3.2`. Releases appear to be frequent, with multiple patch and minor versions released monthly, indicating active development and maintenance. Key differentiators include its automatic IMAP extension handling, built-in mailbox locking for concurrent access, and comprehensive TypeScript support, making it robust for complex email processing applications. It also features specific support for Gmail labels and raw search queries via X-GM-EXT-1.

communication http-networking

npm install imapflow

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · IMAPFLOW

imapflow

communicationjavascriptv1.3.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ImapFlow

✓ import { ImapFlow } from 'imapflow';

✗ const ImapFlow = require('imapflow');

While CommonJS `require` works, the library promotes and ships with full TypeScript support, making ESM imports the idiomatic choice for modern Node.js projects.

ImapFlowOptions

✓ import type { ImapFlowOptions } from 'imapflow';

✗ import { ImapFlowOptions } from 'imapflow';

Always import types using `import type` to ensure they are stripped during compilation, preventing accidental runtime imports.

ImapFlowError

✓ import { ImapFlowError } from 'imapflow';

Common error class provided by the library for specific IMAP-related issues.

This quickstart demonstrates connecting to an IMAP server, acquiring a mailbox lock, fetching the latest message's raw source, and iterating through all messages to log their subjects, ensuring proper resource cleanup.

import { ImapFlow } from 'imapflow'; const client = new ImapFlow({ host: 'imap.example.com', port: 993, secure: true, auth: { user: 'user@example.com', pass: process.env.IMAP_PASSWORD ?? '' // Use environment variable for security } }); const main = async () => { await client.connect(); let lock = await client.getMailboxLock('INBOX'); try { // Fetch the latest message and print its source let message = await client.fetchOne(client.mailbox.exists, { source: true }); if (message?.source) { console.log('Latest message source:', message.source.toString()); } else { console.log('No messages found in INBOX.'); } // List subjects for all messages using an async iterator console.log('\nSubjects of all messages:'); for await (let msg of client.fetch('1:*', { envelope: true })) { console.log(`${msg.uid}: ${msg.envelope?.subject || '(No Subject)'}`); } } finally { // Ensure the mailbox lock is always released lock.release(); } await client.logout(); console.log('\nDisconnected from IMAP server.'); }; main().catch(error => { console.error('An error occurred:', error); // Ensure client disconnects on error if still connected if (client.clientConnected) { client.logout().catch(console.error); } });

Debug

Known issues

gotchaAlways ensure to release mailbox locks obtained via `client.getMailboxLock()` using a `finally` block. Failing to release a lock can lead to resource exhaustion, preventing further operations on the mailbox until the connection is closed or timed out, potentially causing deadlocks or hangs.

fix

Wrap operations requiring a mailbox lock in a `try...finally` block to guarantee `lock.release()` is called, even if errors occur.

affects: >=1.0.0

gotchaImapFlow handles various IMAP extensions automatically, but misconfiguration or server-specific quirks (e.g., non-standard Gmail behavior) can still lead to unexpected results. Always consult the official documentation for advanced features or specific server integrations like Gmail.

fix

Review the 'Configuration' and 'Quick Start' guides on imapflow.com, especially for services like Gmail, Outlook, and Yahoo, to ensure correct options and practices are applied.

affects: >=1.0.0

gotchaEarlier versions might have specific race conditions or unhandled promise rejections during connection close or IDLE recovery, as indicated by recent bug fixes in `v1.2.13` and `v1.2.12`. While patched, always handle connection and disconnection errors robustly.

fix

Upgrade to the latest `imapflow` version (>=1.3.0) to benefit from fixes for unhandled promise rejections. Implement comprehensive error handling around `client.connect()`, `client.logout()`, and `IDLE` operations.

affects: <1.2.13

gotchaSearch conditions involving compound OR/NOT might require explicit parentheses for correct interpretation by the IMAP server (RFC 3501), as highlighted by a fix in `v1.2.16`.

fix

When performing complex search queries, especially with `OR` or `NOT` conditions, ensure they are properly parenthesized according to RFC 3501. Upgrade to `v1.2.16` or newer to get automatic parenthesization for compound conditions.

affects: <1.2.16

Errors

Common errors & fixes

Error: Command 'LOGIN' failed: [AUTHENTICATIONFAILED] Authentication failed.

Incorrect username, password, or application-specific password (for services like Gmail).

fix

Verify credentials. For Gmail, ensure 'Less secure app access' is enabled or use an App Password if 2FA is on. Double-check `auth.user` and `auth.pass` in the ImapFlow client configuration.

Error: Command 'SELECT' failed: [CANNOT SELECT] Folder not found.

Attempting to select a mailbox that does not exist or is misspelled.

fix

Use `client.listMailboxes()` to get a list of available mailboxes and verify the correct name. IMAP mailbox names are case-sensitive on some servers.

TypeError: client.fetchOne is not a function

The `client` object was not properly initialized or `await client.connect()` was not called before attempting operations.

fix

Ensure `new ImapFlow(...)` is called and `await client.connect()` successfully completes before performing any IMAP operations like `fetchOne` or `fetch`.

Promise { <pending> } (unhandled promise rejection)

An asynchronous operation (e.g., `client.connect()`, `client.fetch()`) was not `await`ed, or its returned Promise was not chained with `.catch()` for error handling.

fix

Always `await` ImapFlow's promise-returning methods or attach a `.catch()` handler to them to prevent unhandled promise rejections. Wrap your main async logic in a function and call it with `.catch(console.error)`.

Upgrade

Version history

1.3.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

29 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/postalsys/imapflow ↗

packagehttps://www.npmjs.com/package/imapflow ↗

homepagehttps://imapflow.com/ ↗