ImapFlow

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.

Features

• 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

Installation

npm install imapflow

Quick Example

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.

Documentation

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

Note

If you are looking for a complete email integration solution, ImapFlow was built for EmailEngine, a self-hosted email gateway that provides REST API access to IMAP and SMTP accounts.

License

Copyright (c) 2020-2025 Postal Systems OU

Licensed under the MIT license.