{
  "compilerOptions": {
    "paths": {
      "imapflow/*": ["src/imapflow/*"]
    }
  }
}

Public API

ImapFlow

import { ImapFlow, ImapFlowOptions } from './imapflow/imap-flow';

const client = new ImapFlow(options: ImapFlowOptions);

The main class. Extends EventEmitter. Manages the TCP/TLS connection lifecycle, authentication, mailbox selection, and all IMAP commands. Instantiate once per account session; it is not reusable after logout().

ImapFlowOptions

interface ImapFlowOptions {
  host: string;
  port: number;
  secure?: boolean;
  servername?: string;
  auth?: {
    user: string;
    pass?: string;
    accessToken?: string;
    loginMethod?: string;
    authzid?: string;
  };
  disableCompression?: boolean;
  disableAutoIdle?: boolean;
  qresync?: boolean;
  maxIdleTime?: number;
  proxy?: string;
  logger?: Logger | false;
  logRaw?: boolean;
  verifyOnly?: boolean;
  connectionTimeout?: number;
  greetingTimeout?: number;
  tls?: ConnectionOptions;
}

The configuration object passed to the ImapFlow constructor. host, port, and auth are the only fields needed for a basic connection. Use secure: true for port 993, secure: false with STARTTLS for port 143.

AuthenticationFailure

import { AuthenticationFailure } from './imapflow/tools';

class AuthenticationFailure extends Error {
  authenticationFailed: true;
}

Thrown by client.connect() when credentials are rejected. Check err.authenticationFailed === true to distinguish auth errors from network errors and retry or surface a user-facing message accordingly.

Working examples

Scenario - Connect, lock inbox, fetch latest message source

Establish a TLS connection, acquire a mailbox lock (prevents concurrent access), fetch the raw RFC 822 source of the most recent message, then cleanly release the lock and log out.

import { ImapFlow } from './imapflow/imap-flow';
import { AuthenticationFailure } from './imapflow/tools';

async function fetchLatestSource(): Promise<void> {
  const client = new ImapFlow({
    host: 'imap.example.com',
    port: 993,
    secure: true,
    auth: { user: 'user@example.com', pass: 'secret' },
    logger: false
  });

  try {
    await client.connect();
    const lock = await client.getMailboxLock('INBOX');
    try {
      const msg = await client.fetchOne(client.mailbox.exists, { source: true });
      if (msg) {
        console.log(msg.source.toString());
      }
    } finally {
      lock.release();
    }
    await client.logout();
  } catch (err) {
    if (err instanceof AuthenticationFailure) {
      console.error('Bad credentials:', err.message);
    } else {
      throw err;
    }
  }
}

fetchLatestSource().catch(console.error);

Scenario - Search unseen messages and iterate with async iterator

Use the structured search API to find all unread messages, then stream their envelopes with client.fetch().

import { ImapFlow } from './imapflow/imap-flow';

async function listUnseen(): Promise<void> {
  const client = new ImapFlow({
    host: 'imap.example.com',
    port: 993,
    secure: true,
    auth: { user: 'user@example.com', pass: 'secret' },
    logger: false
  });

  await client.connect();
  const lock = await client.getMailboxLock('INBOX');
  try {
    // search returns an array of sequence numbers / UIDs
    const uids = await client.search({ seen: false }, { uid: true });
    if (uids.length) {
      for await (const msg of client.fetch(uids, { envelope: true, flags: true }, { uid: true })) {
        console.log(msg.uid, msg.envelope.subject, [...msg.flags]);
      }
    }
  } finally {
    lock.release();
  }
  await client.logout();
}

listUnseen().catch(console.error);

Scenario - OAuth2 authentication with proxy

Connect through an HTTP CONNECT proxy using an OAuth2 access token instead of a password.

import { ImapFlow } from './imapflow/imap-flow';

async function oauthViaProxy(): Promise<void> {
  const client = new ImapFlow({
    host: 'imap.gmail.com',
    port: 993,
    secure: true,
    auth: {
      user: 'user@example.com',
      accessToken: process.env.GMAIL_ACCESS_TOKEN!
    },
    proxy: 'http://proxy.corp.internal:3128',
    logger: false
  });

  await client.connect();
  const lock = await client.getMailboxLock('INBOX');
  try {
    console.log(`Total messages: ${client.mailbox.exists}`);
  } finally {
    lock.release();
  }
  await client.logout();
}

oauthViaProxy().catch(console.error);

File walkthrough

• imap-flow.js - Defines the ImapFlow class; owns the socket, state machine, event loop, and delegates commands to commands/.
• imap-flow.d.ts - TypeScript declarations; source of truth for option shapes, event names, and method signatures.
• imap-commands.js - Aggregates all command modules so ImapFlow can dispatch by command name.
• tools.js - Shared helpers: encodePath/decodePath for modified UTF-7, formatMessageResponse, AuthenticationFailure, packMessageRange.
• search-compiler.js - Translates a plain JS search object (e.g. { seen: false, from: 'alice' }) into the wire-format IMAP SEARCH attribute list.
• special-use.js - Exports flags (RFC 6154 special-use flag list) and names (per-locale folder name arrays) for heuristic folder detection.
• logger.js - Wraps pino and produces child loggers attached to each connection.
• limited-passthrough.js - Node.js Transform that passes data through up to a configurable byte ceiling, then emits an error or ends.
• proxy-connection.js - Implements HTTP CONNECT and SOCKS4/5 handshakes before handing the socket to the TLS layer.
• charsets.js - Maps IANA charset names to iconv-lite codec strings for decoding message bodies.
• jp-decoder.js - Specialized decoder for Japanese encodings via encoding-japanese.
• commands/ - Individual IMAP command implementations (fetch, search, select, store, append, idle, etc.).
• handler/ - Raw IMAP protocol layer: imap-parser.js reads token streams, imap-compiler.js serialises command objects, imap-stream.js wraps the socket.

Common pitfalls and fixes

• Lock never released: always wrap the lock body in try/finally and call lock.release() in the finally block; an unreleased lock hangs all subsequent commands indefinitely.
• ESM/CJS mismatch: the source uses require(); in an ESM project wrap imports with createRequire or rename consuming files to .cjs.
• Self-signed / private CA TLS errors: pass tls: { rejectUnauthorized: false } for dev, or tls: { ca: fs.readFileSync('ca.pem') } for production.
• GMAIL_ACCESS_TOKEN expiry: OAuth2 tokens are short-lived; the library does not refresh them automatically - obtain a fresh token before each client.connect() call.
• Concurrent mailbox access: ImapFlow is not safe to share across async contexts; instantiate one client per concurrent session or use the built-in getMailboxLock serialisation.
• pino version conflict: if your project pins a different major version of pino, the logger factory in logger.js may break; add pino to your own dependencies at the same version the source requires.

Vibe-coding prompt template

I have vendored the ImapFlow IMAP client library into my project under `src/imapflow/`.
The integration guide is in `src/imapflow/USAGE.md`.
The upstream package is `user@example.com`.

Please help me integrate this library into my existing Node.js/TypeScript project step by step:

1. Read `src/imapflow/USAGE.md` and `src/imapflow/imap-flow.d.ts` for all types and method signatures.
2. Import `ImapFlow` from `src/imapflow/imap-flow.js` and `AuthenticationFailure` from `src/imapflow/tools.js`.
3. Add a connection helper that reads IMAP credentials from environment variables and returns a connected, authenticated `ImapFlow` instance.
4. Add a service method that accepts a mailbox name and a search query object, acquires the mailbox lock, runs the search, fetches envelopes, releases the lock, and returns the results.
5. Ensure all locks are released in finally blocks and the client is logged out after use.
6. Wire the service into my existing Express route at POST /api/mail/search.
7. Add TypeScript types throughout using `src/imapflow/imap-flow.d.ts`.

License and credit

Licensed under the MIT License. Copyright (c) 2020-2025 Postal Systems OU. Source upstream: imapflow on npm, maintained at github.com/postalsys/imapflow.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.