Skip to main content

Configuration

Configuring ImapFlow

This guide covers all configuration options available when creating an ImapFlow client.

Basic Configuration​

The minimal configuration requires just the server details and authentication:

Minimal configuration
const client = new ImapFlow({
    host: 'imap.example.com',
    port: 993,
    secure: true,
    auth: {
        user: 'user@example.com',
        pass: 'password'
    }
});

Connection Options​

host (required)​

The IMAP server hostname.

{
    host: 'imap.gmail.com'
}

port​

The port to connect to. Defaults to 993 (IMAPS) when secure is true, and to 143 (cleartext/STARTTLS) otherwise. As a special case, setting port: 993 without specifying secure implies secure: true.

{
    port: 993
}

secure​

Whether to use TLS for the connection. If true, establishes the connection directly over TLS. If false, a plain connection is used first and, if possible, upgraded to TLS via STARTTLS.

{
    secure: true  // Use TLS (recommended)
}

doSTARTTLS​

Controls STARTTLS behavior explicitly:

  • true - Start unencrypted and upgrade to TLS using STARTTLS before authentication. Fails if STARTTLS is not supported.
  • false - Never use STARTTLS, even if the server supports it. Results in fully unencrypted connection when combined with secure: false.
  • undefined (default) - Attempt STARTTLS if available when secure: false.
{
    secure: false,
    doSTARTTLS: true  // Require STARTTLS upgrade
}

Note: Setting both secure: true and doSTARTTLS: true is invalid and will throw an error.

servername​

Optional servername for SNI (Server Name Indication). Useful when connecting via IP address.

{
    host: '192.168.1.100',
    servername: 'mail.example.com'
}

Authentication Options​

Basic Authentication​

Username and password authentication:

{
    auth: {
        user: 'user@example.com',
        pass: 'password'
    }
}

OAuth2 Authentication​

For services that support OAuth2 (Gmail, Outlook, etc.):

{
    auth: {
        user: 'user@example.com',
        accessToken: 'ya29.a0AfH6SMBx...'
    }
}
tip

ImapFlow expects you to supply a valid access token and does not refresh tokens itself. Obtaining that token, registering the OAuth2 application, running the consent flow, and renewing tokens before they expire, is usually the hardest part of a mailbox integration. If you would rather not build it, EmailEngine manages OAuth2 apps and token refresh for Gmail and Microsoft 365, and runs ImapFlow under the hood.

Custom Authentication Method​

Specify a custom authentication method:

{
    auth: {
        user: 'user@example.com',
        pass: 'password',
        loginMethod: 'AUTH=PLAIN'  // or 'AUTH=LOGIN' or 'LOGIN'
    }
}

Admin Impersonation (SASL PLAIN with authzid)​

For admin access to user mailboxes (Zimbra, Dovecot, etc.):

{
    auth: {
        user: 'admin@example.com',      // Admin credentials
        pass: 'adminpassword',
        authzid: 'user@example.com',    // User to impersonate
        loginMethod: 'AUTH=PLAIN'       // Required for authzid
    }
}

Note: The authzid parameter only works with the AUTH=PLAIN mechanism. The server must support admin delegation/impersonation.

TLS Options​

tls​

Additional TLS options (passed to Node.js TLS module):

{
    tls: {
        rejectUnauthorized: true,  // Verify server certificate (default: true)
        minVersion: 'TLSv1.2',     // Minimum TLS version
        minDHSize: 1024            // Minimum DH parameter size
    }
}

Accepting Self-Signed Certificates​

Warning: Only use this for testing/development:

{
    tls: {
        rejectUnauthorized: false
    }
}

Proxy Configuration​

ImapFlow supports both SOCKS and HTTP CONNECT proxies.

SOCKS Proxy​

{
    proxy: 'socks://proxy.example.com:1080'
}

SOCKS Proxy with Authentication​

{
    proxy: 'socks://username:password@proxy.example.com:1080'
}

HTTP CONNECT Proxy​

{
    proxy: 'http://proxy.example.com:8080'
}

SOCKS4/SOCKS5 Specific​

{
    proxy: 'socks4://proxy.example.com:1080'
    // or
    proxy: 'socks5://proxy.example.com:1080'
}

Logging Options​

logger​

By default, ImapFlow logs through a built-in Pino instance. You can provide a custom logger object, or disable logging by setting logger: false.

warning

Do not pass console as a logger. ImapFlow expects a logger object that exposes trace, debug, info, warn, error, and fatal methods (the same shape as a Pino logger).

Custom Logger​

const pino = require('pino');

{
    logger: pino({
        level: 'debug'
    })
}

Disable Logging​

{
    logger: false  // No logging
}

logRaw​

Log all raw data read and written to socket in base64 encoding:

{
    logRaw: true
}

emitLogs​

Emit log entries as events instead of (or in addition to) logging:

{
    emitLogs: true
}

client.on('log', (entry) => {
    console.log(`${entry.level}: ${entry.msg}`);
});

Connection Management​

No Auto-Reconnect

ImapFlow does not automatically reconnect when the connection is lost. See the Basic Usage guide for information on handling disconnections.

connectionTimeout​

Timeout for establishing a connection (in milliseconds):

{
    connectionTimeout: 90000  // 90 seconds (default)
}

greetingTimeout​

Timeout for receiving server greeting after connection (in milliseconds):

{
    greetingTimeout: 16000  // 16 seconds (default)
}

socketTimeout​

Timeout for socket inactivity (in milliseconds). Connection is terminated if no data is received within this period:

{
    socketTimeout: 300000  // 5 minutes (default)
}

Client Identification​

clientInfo​

Client identification sent to the server via the ID extension:

{
    clientInfo: {
        name: 'My Email Client',
        version: '1.0.0',
        vendor: 'My Company',
        'support-url': 'https://support.example.com'
    }
}

After connecting, you can access server identification via client.serverInfo.

IDLE and Polling Options​

These options control the IDLE extension (RFC 2177) behavior.

disableAutoIdle​

By default, ImapFlow automatically enters IDLE mode after 15 seconds of inactivity. Disable this behavior:

{
    disableAutoIdle: true
}

maxIdleTime​

Automatically break and restart IDLE after specified milliseconds. Useful for servers that drop long-running IDLE connections:

{
    maxIdleTime: 300000  // Restart IDLE every 5 minutes
}

missingIdleCommand​

Command to use for staying connected if server does not support IDLE:

{
    missingIdleCommand: 'NOOP'  // Default. Can also be 'SELECT' or 'STATUS'
}

Extension Options​

disableCompression​

Disable COMPRESS=DEFLATE extension (RFC 4978) even if server supports it:

{
    disableCompression: true
}

disableBinary​

Disable BINARY extension (RFC 3516) for FETCH and APPEND operations. This also disables the FETCH side of BINARY that IMAP4rev2 servers provide without a separate capability:

{
    disableBinary: true
}

disableAutoEnable​

Do not automatically enable extensions (CONDSTORE, UTF8=ACCEPT, QRESYNC, IMAP4rev2):

{
    disableAutoEnable: true
}

disableIMAP4rev2​

By default, ImapFlow enables IMAP4rev2 (RFC 9051) mode when the server advertises support for it. Use this option as a targeted opt-out for servers with broken IMAP4rev2 implementations without losing the other auto-enabled extensions:

{
    disableIMAP4rev2: true
}

Note that IMAP4rev2 removed the \Recent flag: on an IMAP4rev2 session the recent status counter is always reported as 0 and the new/old/recent search keys are rejected with an error.

qresync​

Enable QRESYNC extension (RFC 7162) support. When enabled, EXPUNGE notifications include UID instead of sequence number:

{
    qresync: true
}

Special Options​

verifyOnly​

Connect, authenticate, and immediately disconnect. Useful for testing credentials:

{
    verifyOnly: true
}

includeMailboxes​

When used with verifyOnly, also fetch the list of mailboxes:

{
    verifyOnly: true,
    includeMailboxes: true
}

expungeHandler​

Custom handler for EXPUNGE events. When set, the expunge event is not emitted:

{
    expungeHandler: async (event) => {
        console.log(`Message ${event.uid || event.seq} was deleted from ${event.path}`);
    }
}

id​

Custom instance ID for logs:

{
    id: 'connection-1'
}

Complete Configuration Example​

Complete configuration example
const { ImapFlow } = require('imapflow');

const client = new ImapFlow({
    // Connection
    host: 'imap.example.com',
    port: 993,
    secure: true,
    servername: 'mail.example.com',

    // Authentication
    auth: {
        user: 'user@example.com',
        pass: 'password'
    },

    // TLS
    tls: {
        rejectUnauthorized: true,
        minVersion: 'TLSv1.2'
    },

    // Proxy (optional)
    // proxy: 'socks://proxy.example.com:1080',

    // Logging (uses Pino by default, set to false to disable)
    // logger: false,

    // Timeouts
    connectionTimeout: 90000,
    greetingTimeout: 16000,
    socketTimeout: 300000,

    // Client identification
    clientInfo: {
        name: 'My Email Client',
        version: '1.0.0'
    },

    // IDLE behavior
    disableAutoIdle: false,
    maxIdleTime: 300000,

    // Extensions
    disableCompression: false,
    disableBinary: false,
    qresync: false
});

Environment-Specific Configurations​

Development​

Development configuration
{
    // Logging uses the built-in Pino instance by default
    logRaw: true,  // Log raw IMAP data (base64 encoded) for debugging
    tls: {
        rejectUnauthorized: false  // Only for testing!
    }
}

Production​

Production configuration
{
    logger: false,
    tls: {
        rejectUnauthorized: true,
        minVersion: 'TLSv1.2'
    },
    connectionTimeout: 90000,
    socketTimeout: 300000
}

Next Steps​