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

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.

• Async/await API - all methods return Promises
• Automatic IMAP extension handling - CONDSTORE, QRESYNC, IDLE, COMPRESS, and more
• Message streaming - async iterators for efficient processing
• Mailbox locking - built-in locking mechanism for safe concurrent access
• TypeScript support - type definitions included
• Proxy support - SOCKS and HTTP CONNECT proxies
• Gmail support - labels, raw search via X-GM-EXT-1

npm install imapflow

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 for more examples, including Gmail, Outlook, and Yahoo configuration.

Full documentation is available at imapflow.com.

• Installation - requirements and setup
• Quick Start - your first ImapFlow application
• Basic Usage - core concepts and patterns
• Configuration - connection options and settings
• Fetching Messages - reading email data
• Searching - finding messages with search queries
• Mailbox Management - creating, renaming, and deleting mailboxes
• API Reference - complete method and event documentation

Copyright (c) 2020-2025 Postal Systems OU

Licensed under the MIT license.