ImapFlow

ImapFlow is a modern and easy-to-use IMAP client library for Node.js. The focus for ImapFlow is to provide an easy-to-use API over IMAP without requiring in-depth knowledge of the IMAP protocol.

Install with npm

npm install imapflow

Key Features

• Modern async/await API - All methods return Promises for easy async handling
• Automatic extension handling - IMAP extensions are handled automatically in the background
• Message streaming - Efficient handling of large mailboxes with async iterators
• TypeScript support - Full TypeScript type definitions included
• Comprehensive IMAP support - Supports all major IMAP operations and extensions
• Mailbox locking - Built-in locking mechanism for safe concurrent mailbox access
• Proxy support - SOCKS and HTTP CONNECT proxy support for secure connections
• Gmail support - Gmail-specific extensions including labels and raw search

Looking for a complete email gateway solution?

EmailEngine is a self-hosted email gateway that provides REST API access to IMAP and SMTP accounts, webhooks for mailbox changes, and advanced features like OAuth2, delayed delivery, open and click tracking, bounce detection, and more.

Supported IMAP Extensions

ImapFlow implements RFC 3501 (IMAP4rev1) and automatically detects and uses the following IMAP extensions when available:

Extension	RFC	Description
IDLE	RFC 2177	Real-time notifications without polling
CONDSTORE	RFC 7162	Efficient change tracking with modification sequences
QRESYNC	RFC 7162	Quick mailbox resynchronization
UIDPLUS	RFC 4315	Enhanced UID operations with response data
MOVE	RFC 6851	Atomic message move operation
ID	RFC 2971	Client/server identification
NAMESPACE	RFC 2342	Mailbox namespace information
COMPRESS=DEFLATE	RFC 4978	Connection compression
UTF8=ACCEPT	RFC 6855	UTF-8 mailbox names and headers
BINARY	RFC 3516	Binary content transfer
SPECIAL-USE	RFC 6154	Standard mailbox roles (Sent, Trash, etc.)
X-GM-EXT-1	Google	Gmail-specific features (labels, search)
OBJECTID	RFC 8474	Unique object identifiers
QUOTA	RFC 9208	Mailbox storage quota

Quick Example

Basic usage 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 () => {
    // Connect and authenticate
    await client.connect();

    // Select a mailbox
    let lock = await client.getMailboxLock('INBOX');
    try {
        // Fetch latest message
        let message = await client.fetchOne('*', {
            envelope: true,
            source: true
        });
        console.log(message.envelope.subject);
    } finally {
        lock.release();
    }

    // Logout
    await client.logout();
};

main().catch(console.error);

Why ImapFlow?

Managing an IMAP connection can be complex, but if you're looking for an easy way to integrate email accounts, ImapFlow provides a clean, promise-based API that abstracts away the complexity of the IMAP protocol.

For production email integration needs, ImapFlow was built for EmailEngine Email API, a self-hosted software that converts IMAP accounts into easy-to-use REST interfaces.

What's Next?

• Installation - Get started with ImapFlow
• Quick Start - Your first ImapFlow application
• Basic Usage - Learn the core concepts
• API Reference - Detailed API documentation