ImapFlow

ImapFlow is a modern IMAP client library for Node.js that wraps the IMAP protocol’s complexity behind a clean async/await API. It automatically detects and adapts to server capabilities — CONDSTORE, QRESYNC, IDLE, COMPRESS, and more — so the same application code works across Gmail, Outlook, Yahoo, and self-hosted IMAP servers without protocol-specific branching.

Built by the team behind EmailEngine, ImapFlow includes async iterators for streaming large mailboxes, a built-in mailbox locking mechanism for safe concurrent access, bundled TypeScript definitions, and SOCKS/HTTP proxy support. It’s the mailbox-access counterpart to Nodemailer’s message-sending role, aimed at teams building email clients, sync tools, or automation on top of raw IMAP.

What You Get

• Async/await API with Promise-based methods for every IMAP operation
• Automatic IMAP extension detection (CONDSTORE, QRESYNC, IDLE, COMPRESS) with graceful fallback
• Async iterator-based message streaming for memory-efficient processing of large mailboxes
• Built-in mailbox locking to prevent race conditions during concurrent access
• Bundled TypeScript type definitions
• SOCKS and HTTP CONNECT proxy support, plus Gmail-specific label and raw-search extensions

Common Use Cases

• Building an email client or webmail interface that reads and organizes IMAP mailboxes
• Syncing mail from Gmail, Outlook, or Yahoo into a local database or search index
• Automating mailbox housekeeping (archiving, flagging, moving messages) via scripts
• Powering a self-hosted email API gateway, the same approach EmailEngine takes on top of ImapFlow

Under The Hood

Architecture ImapFlow is built around a single EventEmitter-based ImapFlow class (lib/imap-flow.js, 4,606 lines) that manages a raw TCP/TLS socket connection to an IMAP server, wrapping it with a hand-rolled IMAP protocol parser/compiler pair (lib/handler/imap-parser.js, imap-compiler.js, token-parser.js — 2,151 lines combined) that turns the wire-format IMAP grammar (RFC 3501/9051) into JS objects and back. Commands are organized one file per IMAP verb under lib/commands/ (fetch.js, search.js, idle.js, append.js, and more), each implementing the compile/parse logic for that specific command and dispatched through imap-commands.js. Connection lifecycle — TLS upgrade, STARTTLS, proxy negotiation via proxy-connection.js, deadline/timeout handling via connection-deadline.js — is layered around the raw socket, and mailbox state (UIDVALIDITY, flags, highest modseq) is tracked in a MailboxObject synced via imap-stream.js, which turns the socket’s byte stream into discrete IMAP response tokens for the parser.

Tech Stack Runtime dependencies are deliberately minimal and mostly internal to the Postal Systems ecosystem: @zone-eu/mailsplit for MIME/header parsing, libmime/libbase64/libqp for content-transfer-encoding decoding, iconv-lite and encoding-japanese for charset conversion, socks for SOCKS proxy support, and pino for structured logging. No external HTTP or IMAP protocol library is used — the IMAP wire protocol itself is fully hand-implemented rather than delegated to a third-party parser. Dev tooling uses Grunt (via grunt-contrib-nodeunit) rather than a modern test runner, ESLint 10 with a shared nodemailer config, and Prettier for formatting; the package ships bundled hand-written TypeScript definitions (lib/imap-flow.d.ts, 916 lines) alongside JSDoc typedefs throughout the source for editor tooling.

Code Quality The 43 files under test/ (commands-test.js, imap-parser-test.js, imap-compiler-test.js, connection-edge-cases-test.js, idle-polling-test.js, and more) give solid coverage of both protocol-level parsing and higher-level client behavior, including a dedicated integration suite with a runnable local IMAP test server (imap-flow-server-test.js) and an optional rev2 integration script. Error handling is explicit — a custom AuthenticationFailure error type, connection deadlines to avoid hangs, and consistent ‘error’/‘close’ event emission for async failures. Naming is consistent with IMAP terminology (mailboxLock, highestModseq, uidValidity), and JSDoc typedefs (e.g. MailboxObject) document return shapes throughout imap-flow.js, though the file’s size (4,606 lines) means the core class carries a lot of responsibility rather than being split further.

API Design The public API is a single ImapFlow class with async methods that map cleanly onto IMAP verbs (fetch, search, append, mailboxOpen), plus async-iterator support (for await…of client.fetch(…)) for streaming — a notably ergonomic choice compared to older callback- or stream-based IMAP libraries. The getMailboxLock()/lock.release() pattern makes concurrent-access safety explicit rather than implicit, adding a small amount of required boilerplate (try/finally) in exchange for preventing a common class of bugs. Bundled TypeScript definitions and a documentation site (imapflow.com) with quick-start guides for Gmail, Outlook, and Yahoo lower the barrier to entry significantly, and runnable quick-start examples ship directly in the repo under examples/.