ImapFlow

https://imapflow.com
Admin
ImapFlow is a modern, easy-to-use IMAP client library for Node.js with async/await support,...
Tokens:107,223
Snippets:754
Trust Score:7.5
Update:2 days ago
Show doc for...
Tokens:
Raw
### getQuota example

Source: https://imapflow.com/docs/api/imapflow-client

Gets quota information for a mailbox. The example retrieves quota for 'INBOX' and logs storage usage and limit if available. Returns false if the server does not support QUOTA or the path does not exist.

```javascript
let quota = await client.getQuota('INBOX');  
if (quota && quota.storage) {  
    console.log(`Used: ${quota.storage.usage}/${quota.storage.limit} bytes (${quota.storage.status})`);  
}  
```

--------------------------------

### mailboxCreate example

Source: https://imapflow.com/docs/api/imapflow-client

Creates a new mailbox and subscribes to it. The example shows how to create 'Projects/2024' and log whether it was created. The method rejects if the mailbox cannot be created.

```javascript
let result = await client.mailboxCreate('Projects/2024');  
console.log('Created:', result.created);  
```

--------------------------------

### Complete example using ImapFlow

Source: https://imapflow.com/docs/getting-started/quick-start

A complete working example: connects, lists mailboxes, selects INBOX, fetches latest 10 messages with envelope and flags, logs them with unread indicator, then logs out. Uses fetchAll() to avoid deadlock.

```javascript
const { ImapFlow } = require('imapflow');  
  
const client = new ImapFlow({  
    host: 'imap.example.com',  
    port: 993,  
    secure: true,  
    auth: {  
        user: 'user@example.com',  
        pass: 'your-password'  
    }  
});  
  
async function main() {  
    // Connect  
    await client.connect();  
    console.log('Connected');  
  
    // List mailboxes  
    let mailboxes = await client.list();  
    console.log('Mailboxes:', mailboxes.map(m => m.path).join(', '));  
  
    // Select INBOX  
    let lock = await client.getMailboxLock('INBOX');  
    try {  
        console.log(`INBOX has ${client.mailbox.exists} messages`);  
  
        if (client.mailbox.exists > 0) {  
            // Fetch latest 10 messages (or all if less than 10)  
            let first = Math.max(1, client.mailbox.exists - 9);  
            let messages = await client.fetchAll(`${first}:*`, {  
                envelope: true,  
                flags: true  
            });  
  
            for (let message of messages) {  
                const seen = message.flags.has('\\Seen') ? '' : '[UNREAD] ';  
                console.log(`${seen}${message.uid}: ${message.envelope.subject}`);  
            }  
        }  
    } finally {  
        lock.release();  
    }  
  
    // Logout  
    await client.logout();  
    console.log('Disconnected');  
}  
  
main().catch(console.error);  
```

--------------------------------

### Fetch partial message source with client.fetchOne

Source: https://imapflow.com/docs/guides/fetching-messages

Requests a partial source by specifying start and maxLength in the source option. Fetches only the first 1000 bytes in this example.

```javascript
let message = await client.fetchOne('*', {  
    source: {  
        start: 0,  
        maxLength: 1000  // First 1000 bytes only  
    }  
});  

```

--------------------------------

### Install ImapFlow with yarn

Source: https://imapflow.com/docs/getting-started/installation

Install the ImapFlow package using yarn as an alternative to npm.

```bash
yarn add imapflow  
```

--------------------------------

### status example

Source: https://imapflow.com/docs/api/imapflow-client

Gets mailbox status without selecting it. The example requests messages, unseen, highestModseq, and size for 'INBOX', then logs the unseen count and mailbox size if available.

```javascript
let status = await client.status('INBOX', {  
    messages: true,  
    unseen: true,  
    highestModseq: true,  
    size: true  
});  
console.log(`${status.unseen}/${status.messages} unseen`);  
if (typeof status.size === 'number') {  
    console.log(`Mailbox size: ${status.size} bytes`);  
}  
```

--------------------------------

### Install ImapFlow with npm

Source: https://imapflow.com/docs/getting-started/installation

Install the ImapFlow package using npm. Requires Node.js 20.0 or higher.

```bash
npm install imapflow  
```

--------------------------------

### fetchAll() example: fetch messages and modify flags

Source: https://imapflow.com/docs/api/imapflow-client

Use client.fetchAll() to fetch all messages before resolving. The example fetches messages 1:100 with envelope and then adds the \Seen flag to each message using messageFlagsAdd with uid: true. Safe to run other commands while processing, but all messages are kept in memory.

```javascript
let messages = await client.fetchAll('1:100', { envelope: true });  
for (let message of messages) {  
    await client.messageFlagsAdd(message.uid, ['\Seen'], { uid: true });  
}  

```

--------------------------------

### Deno: Run command with required permissions

Source: https://imapflow.com/docs/getting-started/installation

Run the Deno ImapFlow example with network, environment, and hostname permissions. These are required even with logger: false.

```bash
deno run --allow-net=imap.example.com:993 --allow-env --allow-sys=hostname main.js  
```

--------------------------------

### Verify ImapFlow installation with npm list

Source: https://imapflow.com/docs/getting-started/installation

Run this command in your terminal to confirm that ImapFlow is installed. The output should display the installed version of ImapFlow.

```bash
npm list imapflow  
```

--------------------------------

### Complete ImapFlow Configuration Example

Source: https://imapflow.com/docs/guides/configuration

Full configuration for the ImapFlow client, covering connection, authentication, TLS, proxy, logging, timeouts, client identification, IDLE behavior, and extensions.

```javascript
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
});
```

--------------------------------

### Fetch partial body part with byte range

Source: https://imapflow.com/docs/guides/fetching-messages

Each entry in bodyParts can be an object with key, start, and maxLength to fetch a byte range of a part. Example fetches first 1KB of part 2.

```javascript
let message = await client.fetchOne('*', {  
    bodyParts: [{ key: '2', start: 0, maxLength: 1024 }]  // first 1KB of part 2  
});  

```

--------------------------------

### listTree example

Source: https://imapflow.com/docs/api/imapflow-client

Retrieves mailboxes as a tree structure and recursively prints the folder hierarchy.

```javascript
let tree = await client.listTree();  
  
function printTree(node, indent = '') {  
    if (node.path) {  
        console.log(indent + node.name);  
    }  
    if (node.folders) {  
        for (let folder of node.folders) {  
            printTree(folder, indent + '  ');  
        }  
    }  
}  
printTree(tree);  
```

--------------------------------

### Deno: Import ImapFlow with npm: specifier and connect

Source: https://imapflow.com/docs/getting-started/installation

Example of using ImapFlow on Deno 2 via npm compatibility. Requires network, environment, and hostname permissions even with logger: false.

```javascript
import { ImapFlow } from 'npm:imapflow';  
  
const client = new ImapFlow({  
    host: 'imap.example.com',  
    port: 993,  
    secure: true,  
    auth: {  
        user: 'user@example.com',  
        pass: 'password'  
    },  
    logger: false  
});  
  
await client.connect();  
console.log(await client.status('INBOX', { messages: true }));  
await client.logout();  

```

--------------------------------

### fetch() example: iterate over messages

Source: https://imapflow.com/docs/api/imapflow-client

Use client.fetch() to iterate over messages in the selected mailbox. The example requests envelope and flags for messages in range '1:*' and logs the UID and subject. Do not run other IMAP commands inside the fetch loop to avoid deadlock.

```javascript
for await (let message of client.fetch('1:*', {  
    envelope: true,  
    flags: true  
})) {  
    console.log(message.uid, message.envelope.subject);  
}  

```

--------------------------------

### Basic ImapFlow usage example

Source: https://imapflow.com/docs

Shows how to connect to an IMAP server, select a mailbox, fetch the latest message, and logout using ImapFlow's async/await API. Requires an IMAP server and valid credentials.

```javascript
import { ImapFlow } from 'imapflow';  
// or in CommonJS: 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  
        // (resolves to false if the mailbox is empty)  
        let message = await client.fetchOne('*', {  
            envelope: true  
        });  
        if (message) {  
            console.log(message.envelope.subject);  
        }  
    } finally {  
        lock.release();  
    }  
  
    // Logout  
    await client.logout();  
};  
  
main().catch(console.error);  
```

--------------------------------

### list example

Source: https://imapflow.com/docs/api/imapflow-client

Lists mailboxes and optionally includes status information such as message count and unseen count.

```javascript
let mailboxes = await client.list();  
for (let mailbox of mailboxes) {  
    console.log(mailbox.path, mailbox.specialUse || '');  
}  
  
// With status query  
let mailboxes = await client.list({  
    statusQuery: { messages: true, unseen: true }  
});  
```

--------------------------------

### fetchOne() example: fetch a single message

Source: https://imapflow.com/docs/api/imapflow-client

Use client.fetchOne() to fetch a single message. The example fetches the last message ('*') with envelope and source, and logs the subject if the message exists. Returns false if not found, undefined if no mailbox is selected.

```javascript
let message = await client.fetchOne('*', {  
    envelope: true,  
    source: true  
});  
if (message) {  
    console.log(message.envelope.subject);  
}  

```

--------------------------------

### SOCKS Proxy with Authentication

Source: https://imapflow.com/docs/guides/configuration

Includes credentials in the proxy URL for proxy authentication. The example uses username and password for a SOCKS proxy.

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

```

--------------------------------

### search() examples: simple, complex, Gmail raw, and ESEARCH

Source: https://imapflow.com/docs/api/imapflow-client

Shows four usage patterns for client.search(): a simple search for unseen messages returning UIDs, a complex search using OR, since, and larger criteria, a Gmail raw search using the gmraw option, and an ESEARCH request returning only the count and highest matching UID. The ESEARCH example logs result.count and result.max.

```javascript
// Simple search  
let uids = await client.search({ seen: false }, { uid: true });  
  
// Complex search  
let uids = await client.search({  
    or: [  
        { from: 'alice@example.com' },  
        { from: 'bob@example.com' }  
    ],  
    since: new Date('2024-01-01'),  
    larger: 10000  
}, { uid: true });  
  
// Gmail raw search  
let uids = await client.search({  
    gmraw: 'has:attachment larger:5M'  
}, { uid: true });  
  
// ESEARCH: get only the count and highest matching UID  
let result = await client.search({ seen: false }, {  
    uid: true,  
    returnOptions: ['COUNT', 'MAX']  
});  
console.log(result.count, result.max);  
```

--------------------------------

### client.search() with returnOptions

Source: https://imapflow.com/docs/guides/searching

Performs a search with returnOptions to get summary counts (COUNT, MIN, MAX) instead of a full list of UIDs. Returns an object with count, min, max properties when ESEARCH is supported.

```APIDOC
## client.search()

### Description
Performs a search with returnOptions to get summary counts (COUNT, MIN, MAX) instead of a full list of UIDs. Returns an object with count, min, max properties when ESEARCH is supported.

### Method
search

### Endpoint
client.search(searchCriteria, options)

### Parameters
#### searchCriteria (object) - Required - Search criteria, e.g., { seen: false }
#### options (object) - Required - Search options
- **uid** (boolean) - Optional - If true, search uses UIDs
- **returnOptions** (array) - Optional - Array of strings or objects: 'COUNT', 'MIN', 'MAX', 'ALL', or { partial: 'range' }

### Request Example
```javascript
let result = await client.search({ seen: false }, {  
    uid: true,  
    returnOptions: ['COUNT', 'MIN', 'MAX']  
});  
```

### Response
#### Success Response
- **count** (number) - Number of matches
- **min** (number) - Lowest matching UID
- **max** (number) - Highest matching UID
- **all** (string) - Compact sequence set (e.g., "1,5:10,20") when 'ALL' is included
- **partial** (object) - { range: '1:100', messages: '...' } when partial is requested

#### Response Example
```javascript
console.log(result.count); // number of matches  
console.log(result.min);   // lowest matching UID  
console.log(result.max);   // highest matching UID  
```
```

--------------------------------

### Pass search results to fetchAll

Source: https://imapflow.com/docs/guides/searching

Search for UIDs and pass the resulting array directly to `fetchAll()`. The example acquires a mailbox lock, searches for unseen messages, and fetches envelopes. The `fetchAll()` method accepts the array of UIDs directly.

```javascript
let lock = await client.getMailboxLock('INBOX');  
try {  
    let uids = await client.search({ seen: false }, { uid: true });  
  
    if (uids.length > 0) {  
        // fetchAll() accepts the array of UIDs directly  
        let messages = await client.fetchAll(uids, {  
            envelope: true  
        }, { uid: true });  
  
        for (let message of messages) {  
            console.log(message.envelope.subject);  
        }  
    }  
} finally {  
    lock.release();  
}  

```

--------------------------------

### HTTP CONNECT Proxy Configuration

Source: https://imapflow.com/docs/guides/configuration

Sets an HTTP CONNECT proxy URL. The example shows an http:// proxy and a commented alternative for connecting to the proxy over TLS with Basic authentication. The default port is 80 for http: and 443 for https:.

```javascript
{  
    proxy: 'http://proxy.example.com:8080'  
    // or connect to the proxy itself over TLS, with Basic authentication  
    // proxy: 'https://username:password@proxy.example.com:443'  
}  

```

--------------------------------

### Require STARTTLS with doSTARTTLS

Source: https://imapflow.com/docs/guides/configuration

Sets secure to false and doSTARTTLS to true to require a STARTTLS upgrade before authentication. connect() fails if the server does not offer STARTTLS. Setting both secure and doSTARTTLS to true is a misconfiguration.

```javascript
{  
    secure: false,  
    doSTARTTLS: true  // Require STARTTLS upgrade  
}  

```

--------------------------------

### Create mailbox with manual delimiter

Source: https://imapflow.com/docs/guides/mailbox-management

When building the path string yourself, get the delimiter from the listing and join the path segments manually. The namespace prefix is still added automatically if the path does not already start with it.

```javascript
let mailboxes = await client.list();  
let delimiter = mailboxes[0]?.delimiter || '/';  
  
let path = ['Projects', '2024', 'ImapFlow'].join(delimiter);  
await client.mailboxCreate(path);  
```

--------------------------------

### Configure download options with client.download()

Source: https://imapflow.com/docs/guides/fetching-messages

Shows the available options for download(): uid, maxBytes, chunkSize, and binary. The stream ends after maxBytes bytes, and chunkSize controls the bytes requested per FETCH.

```javascript
let { meta, content } = await client.download(messageUid, '2', {  
    uid: true,              // messageUid is a UID, not a sequence number  
    maxBytes: 1024 * 1024,  // stop after the first 1MB of decoded content  
    chunkSize: 64 * 1024,   // bytes requested per FETCH (default 65536)  
    binary: true            // let the server decode the part if it supports BINARY  
});  

```

--------------------------------

### mailboxDelete example

Source: https://imapflow.com/docs/api/imapflow-client

Deletes a mailbox and all its messages. The example deletes 'Temporary'. The method rejects if the mailbox does not exist or cannot be deleted.

```javascript
await client.mailboxDelete('Temporary');  
```

--------------------------------

### Install postal-mime

Source: https://imapflow.com/docs/getting-started/quick-start

Installs the postal-mime package via npm, which is required for parsing the raw message source returned by ImapFlow.

```bash
npm install postal-mime  

```

--------------------------------

### connect()

Source: https://imapflow.com/docs/api/imapflow-client

Establishes connection to the IMAP server and authenticates. Rejects if connecting or authenticating fails. An instance can only connect once, calling connect() again rejects with code InstanceReused, so create a new ImapFlow object to reconnect.

```APIDOC
## connect()

### Description
Establishes connection to the IMAP server and authenticates. Rejects if connecting or authenticating fails. An instance can only connect once, calling `connect()` again rejects with code `InstanceReused`, so create a new `ImapFlow` object to reconnect.

### Method
connect()

### Returns
Promise<void>

### Example
```
await client.connect();  
console.log('Connected and authenticated');  
```
```

--------------------------------

### Download multiple parts with client.downloadMany()

Source: https://imapflow.com/docs/guides/fetching-messages

Fetches multiple parts in a single command and returns Buffers instead of streams. The result is an object keyed by part number, each with meta and content. Unlike download(), text is not converted to UTF-8, so check meta.charset.

```javascript
// Download multiple parts at once (returns Buffers, not streams)  
let parts = await client.downloadMany(messageUid, ['1', '2', '3'], { uid: true });  

for (let [partId, data] of Object.entries(parts)) {  
    console.log(`Part ${partId}:`);  
    console.log('  Content-Type:', data.meta.contentType);  
    console.log('  Filename:', data.meta.filename);  
    console.log('  Size:', data.content?.length);  
}  

```

--------------------------------

### List mailboxes

Source: https://imapflow.com/docs/getting-started/quick-start

Lists all available mailboxes. Uses client.listTree() to get the mailbox tree and client.list() to get a flat array of mailboxes, printing each mailbox's path and specialUse.

```javascript
// Get the mailbox tree  
let tree = await client.listTree();  
console.log(tree);  
  
// Or list all mailboxes as a flat array  
let list = await client.list();  
for (let mailbox of list) {  
    console.log(mailbox.path, mailbox.specialUse || '');  
}  

```

--------------------------------

### Connect to IMAP server

Source: https://imapflow.com/docs/api/imapflow-client

Establishes connection and authenticates. Rejects on failure. Can only be called once; subsequent calls reject with code 'InstanceReused'.

```javascript
await client.connect();  
console.log('Connected and authenticated');  

```

--------------------------------

### upgradeToSTARTTLS()

Source: https://imapflow.com/docs/api/imapflow-client

Upgrades the current connection to TLS using STARTTLS. This is typically called automatically when secure: false and the server supports STARTTLS.

```APIDOC
## upgradeToSTARTTLS()

### Description
Upgrades the current connection to TLS using STARTTLS. This is typically called automatically when `secure: false` and the server supports STARTTLS.

### Method
upgradeToSTARTTLS()

### Returns
Promise<Boolean> - `true` if the connection is now protected by TLS (direct TLS or STARTTLS), `false` otherwise. Rejects if STARTTLS is required (`doSTARTTLS: true`) but not possible.

### Example
```
// Manual STARTTLS upgrade (usually not needed)  
const upgraded = await client.upgradeToSTARTTLS();  
if (upgraded) {  
    console.log('Connection is protected by TLS');  
}  
```
```

--------------------------------

### listTree(options)

Source: https://imapflow.com/docs/api/imapflow-client

Gets mailboxes organized as a tree structure.

```APIDOC
## listTree(options)

### Description
Gets mailboxes organized as a tree structure.

### Method
N/A (Client method)

### Parameters
#### Options
- **options** (Object) - Optional - Same as list()

### Returns
Promise<ListTreeResponse>
The root node has `root: true` and only a `folders` array. Other nodes carry `path`, `name`, `delimiter`, `flags`, `specialUse`, `listed`, `subscribed`, `disabled` (`true` if the mailbox can not be selected) and `folders`. If `statusQuery` was used, each node also carries a `status` property with the corresponding StatusObject.

### Example
```javascript
let tree = await client.listTree();

function printTree(node, indent = '') {
    if (node.path) {
        console.log(indent + node.name);
    }
    if (node.folders) {
        for (let folder of node.folders) {
            printTree(folder, indent + '  ');
        }
    }
}
printTree(tree);
```
```

--------------------------------

### Complete ImapFlow client example

Source: https://imapflow.com/docs/guides/basic-usage

This snippet shows a full ImapFlow workflow: create a client with host, port, secure, and auth options, disable logging, handle 'error' and 'close' events, connect, list mailboxes, lock INBOX, fetch the latest message's envelope and flags, release the lock, and logout. It includes try/catch/finally for error handling and cleanup.

```javascript
const { ImapFlow } = require('imapflow');  
  
async function main() {  
    const client = new ImapFlow({  
        host: 'imap.example.com',  
        port: 993,  
        secure: true,  
        auth: {  
            user: 'user@example.com',  
            pass: 'password'  
        },  
        logger: false  // Disable logging for cleaner output  
    });  
  
    // Handle connection events  
    client.on('error', err => {  
        console.error('Connection error:', err);  
    });  
  
    client.on('close', () => {  
        console.log('Connection closed');  
    });  
  
    try {  
        // Connect  
        await client.connect();  
        console.log('Connected to', client.host);  
  
        // List mailboxes  
        let mailboxes = await client.list();  
        console.log('Available mailboxes:');  
        for (let mailbox of mailboxes) {  
            console.log(`  ${mailbox.path} ${mailbox.specialUse || ''}`);  
        }  
  
        // Work with INBOX  
        let lock = await client.getMailboxLock('INBOX');  
        try {  
            console.log(`\nINBOX has ${client.mailbox.exists} messages`);  
  
            if (client.mailbox.exists > 0) {  
                // Fetch latest message  
                let message = await client.fetchOne('*', {  
                    envelope: true,  
                    flags: true  
                });  
  
                console.log('\nLatest message:');  
                console.log('  Subject:', message.envelope.subject);  
                console.log('  From:', message.envelope.from[0]?.address);  
                console.log('  Date:', message.envelope.date);  
                console.log('  Read:', message.flags.has('\\Seen'));  
            }  
        } finally {  
            lock.release();  
        }  
  
        // Logout  
        await client.logout();  
        console.log('\nDisconnected');  
  
    } catch (err) {  
        console.error('Error:', err);  
        client.close();  
    }  
}  
  
main();  
```

--------------------------------

### new ImapFlow(options)

Source: https://imapflow.com/docs/api/imapflow-client

Creates a new IMAP client instance with the provided configuration options. This constructor initializes the client with settings for connection, authentication, logging, and protocol features.

```APIDOC
## new ImapFlow(options)

### Description
Creates a new IMAP client instance with the specified configuration options.

### Method
Constructor

### Parameters
#### options (ImapFlowOptions) - Required
Configuration options for the IMAP client.

- **host** (String) - Optional - IMAP server hostname (defaults to `localhost`)
- **port** (Number) - Optional - Port number (defaults to 993 if `secure: true`, otherwise 143)
- **secure** (Boolean) - Optional - If `true`, establishes the connection directly over TLS. If `false` (default), uses plain TCP and may upgrade via STARTTLS unless `doSTARTTLS: false` is set. Setting `port: 993` without `secure` implies `secure: true`.
- **doSTARTTLS** (Boolean) - Optional - STARTTLS (RFC 2595) policy for a connection not opened with `secure: true`. `true` requires the upgrade (connecting fails if the server does not offer STARTTLS), `false` keeps the connection in cleartext. If not set, the connection upgrades when the server offers STARTTLS and otherwise continues in cleartext with a warning logged. Setting both `doSTARTTLS: true` and `secure: true` is rejected as a misconfiguration.
- **servername** (String) - Optional - Servername for SNI (for IP addresses or custom names)
- **auth** (Object) - Optional - Authentication credentials
  - **user** (String) - Username
  - **pass** (String) - Password
  - **accessToken** (String) - OAuth2 access token (alternative to pass)
  - **loginMethod** (String) - Optional override: 'LOGIN', 'AUTH=LOGIN', or 'AUTH=PLAIN'
  - **authzid** (String) - Authorization identity for SASL PLAIN (admin impersonation)
- **logger** (Object|Boolean) - Optional - Logger object with `debug`, `info`, `warn` and `error` methods (`trace` and `fatal` are used when present), for example a pino or bunyan instance. Set to `false` to disable logging, omit to use the built-in pino logger
- **tls** (Object) - Optional - Additional TLS options passed to Node.js `tls.connect()`
- **proxy** (String) - Optional - Proxy URL. Supports HTTP CONNECT (`http:`, `https:`) and SOCKS (`socks:`, `socks4:`, `socks4a:`, `socks5:`) proxies. IPv6 proxy endpoints use URL form, e.g. `socks5://[2001:db8::1]:1080`
- **transport** (Object) - Optional - Opens the connection through this transport instead of Node.js `net` and `tls`, see Transport Functions and Custom Transport. Can not be combined with `proxy`
- **clientInfo** (Object) - Optional - Client identification sent with the ID command (RFC 2971): `name`, `version`, `os`, `vendor`, `support-url`, `date` and any other field
- **disableAutoIdle** (Boolean) - Optional - Do not start IDLE (RFC 2177) automatically when the connection is inactive
- **autoIdleDelay** (Number|String) - Optional - How long in ms the connection has to be inactive before IDLE starts automatically (default: 15000). Capped below `socketTimeout`. Use `disableAutoIdle` to turn auto-IDLE off rather than a very large delay
- **disableCompression** (Boolean) - Optional - Do not use COMPRESS=DEFLATE (RFC 4978) even if the server supports it
- **disableBinary** (Boolean) - Optional - Ignore the BINARY extension (RFC 3516) for FETCH and APPEND
- **disableAutoEnable** (Boolean) - Optional - Do not ENABLE (RFC 5161) supported extensions automatically
- **disableIMAP4rev2** (Boolean) - Optional - Do not enable IMAP4rev2 (RFC 9051) mode even if the server advertises it, and do not treat the advertisement as support for anything IMAP4rev2 implies
- **qresync** (Boolean) - Optional - Use QRESYNC (RFC 7162) instead of CONDSTORE. EXPUNGE notifications then include the UID
- **maxIdleTime** (Number) - Optional - If set, break and restart IDLE every `maxIdleTime` ms
- **missingIdleCommand** (String) - Optional - Command to run if IDLE is not supported: `'NOOP'` (default), `'SELECT'` or `'STATUS'`
- **connectionTimeout** (Number) - Optional - Time budget in ms for a usable transport, covering DNS, proxy negotiation and the TCP/TLS handshake (default: 90000). Expiry rejects with code `CONNECT_TIMEOUT`
- **greetingTimeout** (Number) - Optional - How long in ms to wait for the server greeting (default: 16000)
- **socketTimeout** (Number) - Optional - Socket inactivity timeout in ms (default: 300000)
- **maxLineLength** (Number) - Optional - Maximum length in bytes of a single response line (default: 1 GB, `Infinity` disables). Exceeding it fails the connection with code `LineTooLarge`
- **maxLiteralSize** (Number) - Optional - Maximum size in bytes of a single IMAP literal (default: 1 GB, `Infinity` disables). Exceeding it fails the connection with code `LiteralTooLarge`
- **maxResponseSize** (Number) - Optional - Maximum total size in bytes of one assembled response (default: 2 GB, `Infinity` disables). Keep it above `maxLiteralSize`. Exceeding it fails the connection with code `ResponseTooLarge`
- **maxLockHoldTime** (Number|Boolean) - Optional - Log a warning when a mailbox lock has been held longer than this many ms, to catch forgotten `release()` calls (default: 30 minutes). Set to `0` or `false` to disable

### Request Example
```javascript
const client = new ImapFlow({
  host: 'imap.example.com',
  port: 993,
  secure: true,
  auth: {
    user: 'user@example.com',
    pass: 'password'
  }
});
```

### Response
No response body. The constructor returns a new ImapFlow client instance.
```

--------------------------------

### client.connect()

Source: https://imapflow.com/docs/guides/basic-usage

Establishes a connection to the IMAP server. Must be called before any other operations.

```APIDOC
## client.connect()

### Description
Establishes a connection to the IMAP server. Must be called before any other operations.

### Method
connect

### Endpoint
client.connect()

### Parameters
None

### Request Example
```javascript
await client.connect();
```

### Response
#### Success Response
No return value.

#### Response Example
```javascript
// No response body
```
```

--------------------------------

### mailboxRename example

Source: https://imapflow.com/docs/api/imapflow-client

Renames a mailbox from 'Old' to 'New'. The method rejects if the mailbox does not exist or cannot be renamed.

```javascript
await client.mailboxRename('Old', 'New');  
```

--------------------------------

### status(path, query)

Source: https://imapflow.com/docs/api/imapflow-client

Gets mailbox status without selecting it. Only the requested values are returned.

```APIDOC
## status(path, query)

### Description
Gets mailbox status without selecting it. Only the requested values are returned.

### Method
status

### Parameters
- **path** (String|Array) - Required - Mailbox path (e.g., 'INBOX', ['INBOX', 'Subfolder'])
- **query** (Object) - Required - Status items to fetch
  - **messages** (Boolean) - Total message count
  - **recent** (Boolean) - Recent message count (always 0 on IMAP4rev2 sessions - the \Recent flag was removed in RFC 9051)
  - **uidNext** (Boolean) - Next UID value
  - **uidValidity** (Boolean) - UIDVALIDITY value
  - **unseen** (Boolean) - Unseen message count
  - **highestModseq** (Boolean) - Highest modseq value
  - **size** (Boolean) - Total mailbox size in octets (requires STATUS=SIZE (RFC 8438) or IMAP4rev2)
  - **deleted** (Boolean) - Count of messages with the \Deleted flag (requires IMAP4rev2)

### Returns
Promise<StatusObject|false> - an object with `path` plus the requested values, or `false` if the server rejected the request

### Example
```javascript
let status = await client.status('INBOX', {
    messages: true,
    unseen: true,
    highestModseq: true,
    size: true
});
console.log(`${status.unseen}/${status.messages} unseen`);
if (typeof status.size === 'number') {
    console.log(`Mailbox size: ${status.size} bytes`);
}
```
```

--------------------------------

### fetchOne with Query Macros

Source: https://imapflow.com/docs/guides/fetching-messages

Fetches a message using convenience macros FAST, ALL, and FULL that expand into individual data items.

```APIDOC
## fetchOne with Query Macros

### Description
Fetches a message using convenience macros FAST, ALL, and FULL that expand into individual data items.

### Method
fetchOne

### Endpoint
client.fetchOne('*', { fast: true }) / client.fetchOne('*', { all: true }) / client.fetchOne('*', { full: true })

### Parameters
#### Query Options
- **fast** (boolean) - Optional - Expands to flags, internalDate, size.
- **all** (boolean) - Optional - Expands to flags, internalDate, size, envelope.
- **full** (boolean) - Optional - Expands to flags, internalDate, size, envelope, bodyStructure.

### Request Example
```javascript
// FAST macro: flags, internalDate, size  
let message = await client.fetchOne('*', { fast: true });  
  
// ALL macro: flags, internalDate, size, envelope  
let message = await client.fetchOne('*', { all: true });  
  
// FULL macro: flags, internalDate, size, envelope, bodyStructure  
let message = await client.fetchOne('*', { full: true });  
```

### Response
#### Success Response
- **flags** (array) - Message flags.
- **internalDate** (Date) - Internal date.
- **size** (number) - Message size.
- **envelope** (object) - Envelope data (for all and full).
- **bodyStructure** (object) - Body structure (for full).

### Notes
- ImapFlow expands the macros into the individual data items before sending the command, so they can be combined with other query options such as source or headers.
```

--------------------------------

### Create a new mailbox with mailboxCreate()

Source: https://imapflow.com/docs/guides/mailbox-management

Creates a mailbox named 'Projects' and logs the result. The method subscribes to the new mailbox automatically. If the mailbox already exists, it resolves with `created: false` instead of throwing. Unicode names are encoded as modified UTF-7 unless the server supports UTF8=ACCEPT.

```javascript
let result = await client.mailboxCreate('Projects');  
console.log('Path:', result.path);  
console.log('Created:', result.created);     // false if the mailbox already existed  
console.log('Mailbox ID:', result.mailboxId); // only with OBJECTID (RFC 8474)  

```

--------------------------------

### getQuota(path)

Source: https://imapflow.com/docs/api/imapflow-client

Gets quota information (RFC 9208) for a mailbox. Defaults to INBOX if no path is provided.

```APIDOC
## getQuota(path)

### Description
Gets quota information (RFC 9208) for a mailbox. Defaults to INBOX if no path is provided.

### Method
getQuota

### Parameters
- **path** (String|Array) - Optional - Mailbox path (defaults to 'INBOX'), e.g. 'INBOX' or ['INBOX', 'Subfolder']

### Returns
Promise<QuotaResponse|false> - `false` if the server does not support the QUOTA extension or the path does not exist

### Example
```javascript
let quota = await client.getQuota('INBOX');
if (quota && quota.storage) {
    console.log(`Used: ${quota.storage.usage}/${quota.storage.limit} bytes (${quota.storage.status})`);
}
```
```

--------------------------------

### client.downloadMany()

Source: https://imapflow.com/docs/guides/fetching-messages

Downloads multiple parts at once in a single command. Returns an object keyed by part number, each entry holding meta and content (a Buffer).

```APIDOC
## client.downloadMany()

### Description
Fetches multiple parts in a single command and resolves with an object keyed by part number, each entry holding `meta` and `content` (a Buffer). The content has its transfer encoding removed, but unlike `download()` text is not converted to UTF-8, so check `meta.charset`.

### Method
`downloadMany`

### Signature
`client.downloadMany(message, parts, options?)`

### Parameters
- **message** (string|number) - Required - Message identifier. Use a sequence number or UID depending on the `uid` option.
- **parts** (array) - Required - Array of part numbers to download.
- **options** (object) - Optional - Download options.
  - **uid** (boolean) - Optional - If `true`, `message` is a UID instead of a sequence number.
  - **maxBytes** (number) - Optional - Stop after the first N bytes of decoded content (applied to each part).
  - **binary** (boolean) - Optional - Let the server decode the part if it supports BINARY.

### Return Value
Resolves with an object keyed by part number, each entry holding:
- **meta** (object) - Metadata about the part (same properties as `download()`).
- **content** (Buffer) - The decoded content as a Buffer.

### Example
```javascript
// Download multiple parts at once (returns Buffers, not streams)
let parts = await client.downloadMany(messageUid, ['1', '2', '3'], { uid: true });

for (let [partId, data] of Object.entries(parts)) {
    console.log(`Part ${partId}:`);
    console.log('  Content-Type:', data.meta.contentType);
    console.log('  Filename:', data.meta.filename);
    console.log('  Size:', data.content?.length);
}
```

### Notes
- Because every part is loaded into memory, use `download()` for large attachments.
```

--------------------------------

### Get connection byte counters

Source: https://imapflow.com/docs/api/imapflow-client

Returns sent and received byte counters. Optionally resets counters if reset is true.

```javascript
let { sent, received } = client.stats();  
console.log(`Sent ${sent} bytes, received ${received} bytes`);  

```

--------------------------------

### client.search() - AND combination

Source: https://imapflow.com/docs/guides/searching

Demonstrates how to combine multiple search criteria with AND by placing them in a single object. All criteria must be satisfied.

```APIDOC
## client.search() - AND combination

### Description
Combines multiple search criteria with AND. All criteria in a single object must be true.

### Method
client.search()

### Parameters
- **criteria** (object) - Required - An object where each key is a search criterion (e.g., `seen`, `from`, `larger`). All keys are ANDed together.
- **options** (object) - Optional - An object with `uid: true` to return UIDs instead of sequence numbers.

### Request Example
```javascript
let uids = await client.search({
    seen: false,
    from: 'boss@example.com',
    larger: 10 * 1024
}, { uid: true });
```

### Response
Returns an array of message UIDs (or sequence numbers) matching the criteria.
```

--------------------------------

### expungeHandler

Source: https://imapflow.com/docs/guides/configuration

Custom handler for deleted messages, called with the same object the `expunge` event would get. When set, the `expunge` event is not emitted.

```APIDOC
## expungeHandler

### Description
Custom handler for deleted messages, called with the same object the `expunge` event would get. When set, the `expunge` event is not emitted. Unlike an event listener, the handler is awaited, and an error it throws is logged instead of being propagated.

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

--------------------------------

### fetchOne with Partial Body Part

Source: https://imapflow.com/docs/guides/fetching-messages

Fetches a byte range of a specific body part using an object with key, start, and maxLength.

```APIDOC
## fetchOne with Partial Body Part

### Description
Fetches a byte range of a specific body part using an object with key, start, and maxLength.

### Method
fetchOne

### Endpoint
client.fetchOne('*', { bodyParts: [{ key: '2', start: 0, maxLength: 1024 }] })

### Parameters
#### Query Options
- **bodyParts** (array) - Required - Array of objects with properties:
  - **key** (string) - Required - Part number.
  - **start** (number) - Required - Byte offset to start from.
  - **maxLength** (number) - Required - Maximum number of bytes to fetch.

### Request Example
```javascript
let message = await client.fetchOne('*', {  
    bodyParts: [{ key: '2', start: 0, maxLength: 1024 }]  // first 1KB of part 2  
});  
```

### Response
#### Success Response
- **bodyParts** (Map) - Map with the requested part key (lowercase) to Buffer containing the byte range.
```

--------------------------------

### client.mailboxCreate(path)

Source: https://imapflow.com/docs/guides/mailbox-management

Creates a new mailbox. If the mailbox already exists, it resolves with `created: false` instead of throwing. Automatically subscribes to the new mailbox.

```APIDOC
## client.mailboxCreate(path)

### Description
Creates a new mailbox. If the mailbox already exists, it resolves with `created: false` instead of throwing. Automatically subscribes to the new mailbox.

### Method
CREATE

### Endpoint
N/A (ImapFlow client method)

### Parameters
#### Path Parameters
- **path** (string or array) - Required - The mailbox path. Can be a string (e.g., `'Projects'`) or an array of path segments (e.g., `['Work', 'Projects', 'ImapFlow']`). Unicode names are allowed.

### Request Example
```javascript
let result = await client.mailboxCreate('Projects');
```

### Response
#### Success Response
- **path** (string) - The full path of the created mailbox.
- **created** (boolean) - `true` if the mailbox was created, `false` if it already existed.
- **mailboxId** (string) - The mailbox ID (only if the server supports OBJECTID, RFC 8474).

#### Response Example
```javascript
{
  path: 'Projects',
  created: true,
  mailboxId: 'abc123'
}
```
```

--------------------------------

### Connect to IMAP server

Source: https://imapflow.com/docs/getting-started/quick-start

Uses async/await to connect to the IMAP server. The client.connect() method waits until the client connects and authorizes. Errors are caught and logged.

```javascript
async function main() {  
    // Wait until client connects and authorizes  
    await client.connect();  
    console.log('Connected to IMAP server');  
}  
  
main().catch(err => {  
    console.error('Connection error:', err);  
});  

```

--------------------------------

### Checking Connection State

Source: https://imapflow.com/docs/api/imapflow-client

Compare the `state` property against the `states` constants to determine if a mailbox is selected. The example logs a message when the client is in the `SELECTED` state.

```javascript
if (client.state === client.states.SELECTED) {  
    console.log('A mailbox is selected');  
}  

```

--------------------------------

### celld: ImapFlow worker with createSocketsTransport

Source: https://imapflow.com/docs/getting-started/installation

Example of using ImapFlow on celld with cloudflare:sockets connect. Without this transport, connect() fails with 'node:net.connect is not implemented in celld'.

```javascript
import { connect } from 'cloudflare:sockets';  
import { ImapFlow, createSocketsTransport } from 'imapflow';  
  
export default {  
    async fetch(request, env, ctx) {  
        const client = new ImapFlow({  
            host: 'imap.example.com',  
            port: 993,  
            secure: true,  
            auth: { user: 'user@example.com', pass: 'password' },  
            logger: false,  
            transport: createSocketsTransport(connect)  
        });  
        await client.connect();  
        const status = await client.status('INBOX', { messages: true });  
        await client.logout();  
        return Response.json(status);  
    }  
};  

```
Tokens:
Raw