imapflow 1.7.1 → 1.7.3

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-    ".": "1.7.1"
+    ".": "1.7.3"
 }

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [1.7.3](https://github.com/postalsys/imapflow/compare/v1.7.2...v1.7.3) (2026-08-24)
+
+
+### Bug Fixes
+
+* **errors:** make the rejection guard structural and stamp every connection error ([67a4afc](https://github.com/postalsys/imapflow/commit/67a4afcc06a2699ea327e98459590901f2efb24c))
+* **errors:** name the rejection site on connection errors and guard the IDLE preCheck waiter ([55764f0](https://github.com/postalsys/imapflow/commit/55764f056f5aeb9771e493e9b659872f01ee7995))
+
+## [1.7.2](https://github.com/postalsys/imapflow/compare/v1.7.1...v1.7.2) (2026-08-21)
+
+
+### Bug Fixes
+
+* **envelope:** stop inventing an address from a NIL host field ([253a7b0](https://github.com/postalsys/imapflow/commit/253a7b0747ebe3c59fb177d46eb9843da6b5e91e))
+* **types:** accept string[] paths in status, getQuota, append, copy and move ([92f3607](https://github.com/postalsys/imapflow/commit/92f360749fd9518532f0d908bf246fb9402f2eaa)), closes [#382](https://github.com/postalsys/imapflow/issues/382)
+
 ## [1.7.1](https://github.com/postalsys/imapflow/compare/v1.7.0...v1.7.1) (2026-08-14)
 
 

package/lib/commands/fetch.js

@@ -254,7 +254,7 @@ module.exports = async (connection, range, query, options) => {
                 // the FETCH on a connection that is already gone.
                 let aborted = await connection.throttleWait(delay);
                 if (aborted) {
-                    throw connection.createNoConnectionError(connection.byeReason);
+                    throw connection.createNoConnectionError(connection.byeReason, { rejectedFrom: 'throttleAbort', command: 'FETCH' });
                 }
 
                 retryCount++;

package/lib/commands/idle.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { hasCapability, logConnectionError, unrefTimer } = require('../tools.js');
+const { guardedPromise, hasCapability, logConnectionError, unrefTimer } = require('../tools.js');
 
 const NOOP_INTERVAL = 2 * 60 * 1000;
 
@@ -85,7 +85,9 @@ async function runIdle(connection) {
         // Public interface for breaking IDLE. Returns a promise that resolves when
         // IDLE is actually broken and the connection is free for other commands.
         let connectionPreCheck = () => {
-            let handler = new Promise((resolve, reject) => {
+            // Guarded: the catch block below rejects every queued waiter synchronously while
+            // close() tears the connection down. See guardedPromise().
+            let handler = guardedPromise((resolve, reject) => {
                 preCheckWaitQueue.push({ resolve, reject });
             });
 

package/lib/imap-flow.d.ts

@@ -787,7 +787,7 @@ export class ImapFlow extends EventEmitter {
     close(): void;
 
     /** Returns current quota */
-    getQuota(path?: string): Promise<QuotaResponse | false>;
+    getQuota(path?: string | string[]): Promise<QuotaResponse | false>;
 
     /** Lists available mailboxes as an Array */
     list(options?: ListOptions): Promise<ListResponse[]>;
@@ -821,7 +821,7 @@ export class ImapFlow extends EventEmitter {
 
     /** Requests the status of the indicated mailbox */
     status(
-        path: string,
+        path: string | string[],
         query: {
             messages?: boolean;
             recent?: boolean;
@@ -855,13 +855,21 @@ export class ImapFlow extends EventEmitter {
     messageDelete(range: SequenceString | number[] | SearchObject, options?: { uid?: boolean }): Promise<boolean>;
 
     /** Appends a new message to a mailbox */
-    append(path: string, content: string | Buffer, flags?: string[], idate?: Date | string): Promise<AppendResponseObject | false>;
+    append(path: string | string[], content: string | Buffer, flags?: string[], idate?: Date | string): Promise<AppendResponseObject | false>;
 
     /** Copies messages from current mailbox to destination mailbox */
-    messageCopy(range: SequenceString | number[] | SearchObject, destination: string, options?: { uid?: boolean }): Promise<CopyResponseObject | false>;
+    messageCopy(
+        range: SequenceString | number[] | SearchObject,
+        destination: string | string[],
+        options?: { uid?: boolean }
+    ): Promise<CopyResponseObject | false>;
 
     /** Moves messages from current mailbox to destination mailbox */
-    messageMove(range: SequenceString | number[] | SearchObject, destination: string, options?: { uid?: boolean }): Promise<CopyResponseObject | false>;
+    messageMove(
+        range: SequenceString | number[] | SearchObject,
+        destination: string | string[],
+        options?: { uid?: boolean }
+    ): Promise<CopyResponseObject | false>;
 
     /** Search messages from the currently opened mailbox — returns number[] (backward-compatible) */
     search(query: SearchObject, options?: { uid?: boolean }): Promise<number[] | false>;

package/lib/imap-flow.js

@@ -43,13 +43,13 @@ const {
     parseUintValue,
     isUnsafeKey,
     getStringList,
+    guardedPromise,
+    guardedReject,
     MAX_UINT32_DIGITS
 } = require('./tools');
 
 const imapCommands = require('./imap-commands.js');
 
-const noop = () => {};
-
 const GREETING_TIMEOUT = 16 * 1000;
 const UPGRADE_TIMEOUT = 10 * 1000;
 
@@ -677,16 +677,12 @@ class ImapFlow extends EventEmitter {
     write(chunk) {
         if (!this.socket || this.socket.destroyed) {
             // do not write after connection end or logout
-            const error = new Error('Socket is already closed');
-            error.code = 'NoConnection';
-            throw error;
+            throw this.createConnectionError('NoConnection', 'Socket is already closed', { rejectedFrom: 'writeNoSocket' });
         }
 
         if (this.state === this.states.LOGOUT) {
             // should not happen
-            const error = new Error('Can not send data after logged out');
-            error.code = 'StateLogout';
-            throw error;
+            throw this.createConnectionError('StateLogout', 'Can not send data after logged out', { rejectedFrom: 'writeAfterLogout' });
         }
 
         if (this.writeSocket.destroyed) {
@@ -771,9 +767,7 @@ class ImapFlow extends EventEmitter {
                 let request = this.requestTagMap.get(data.tag);
                 if (request) {
                     this.requestTagMap.delete(request.tag);
-                    const error = new Error('Connection not available');
-                    error.code = 'NoConnection';
-                    request.reject(error);
+                    request.reject(this.createNoConnectionError(false, { rejectedFrom: 'sendAfterLogout', command: request.command }));
                 }
             }
             return;
@@ -864,26 +858,20 @@ class ImapFlow extends EventEmitter {
 
     exec(command, attributes, options) {
         if (this.state === this.states.LOGOUT || this.isClosed) {
-            const error = new Error('Connection not available');
-            error.code = 'NoConnection';
-            let p = Promise.reject(error);
-            p.catch(noop);
-            return p;
+            return guardedReject(this.createNoConnectionError(false, { rejectedFrom: 'execClosed', command }));
         }
 
         if (!this.socket || this.socket.destroyed) {
-            let error = new Error('Connection closed');
-            error.code = 'EConnectionClosed';
-            let p = Promise.reject(error);
-            p.catch(noop);
-            return p;
+            return guardedReject(this.createConnectionError('EConnectionClosed', 'Connection closed', { rejectedFrom: 'execNoSocket', command }));
         }
 
         let tag = (++this.tagCounter).toString(16).toUpperCase();
 
         options = options || {};
 
-        let promise = new Promise((resolve, reject) => {
+        // Guarded: close() rejects this request synchronously, possibly before the caller has
+        // attached its handler. See guardedPromise().
+        return guardedPromise((resolve, reject) => {
             this.requestTagMap.set(tag, { command, attributes, options, resolve, reject });
             this.requestQueue.push({ tag, command, attributes, options });
             // trySend() settles dispatch failures itself, by rejecting the affected
@@ -891,13 +879,6 @@ class ImapFlow extends EventEmitter {
             // dispatch machinery itself can never surface as a floating rejection.
             this.trySend().catch(err => logConnectionError(this, 'Failed to dispatch command', err));
         });
-
-        // Prevent unhandled promise rejection if close() rejects this request
-        // synchronously before the caller's handler is attached. The rejection
-        // still propagates normally to the caller's await/.catch().
-        promise.catch(noop);
-
-        return promise;
     }
 
     // Resolves an untagged server response to the keyword it is dispatched on. IMAP untagged
@@ -1366,7 +1347,7 @@ class ImapFlow extends EventEmitter {
                             // Connection closed during back-off: reject promptly with a
                             // connection error (carrying any server BYE reason) instead of
                             // waiting out the throttle delay.
-                            request.reject(this.createNoConnectionError(this.byeReason));
+                            request.reject(this.createNoConnectionError(this.byeReason, { rejectedFrom: 'throttleAbort', command: request.command }));
                             break;
                         }
                     }
@@ -1865,9 +1846,7 @@ class ImapFlow extends EventEmitter {
                 try {
                     /* c8 ignore start */ // race: connection closed during the TLS handshake window
                     if (this.isClosed) {
-                        let err = new Error('Connection closed during TLS upgrade');
-                        err.code = 'NoConnection';
-                        return settle(err);
+                        return settle(this.createNoConnectionError(false, { rejectedFrom: 'tlsUpgrade' }));
                     }
                     /* c8 ignore stop */
 
@@ -2433,7 +2412,8 @@ class ImapFlow extends EventEmitter {
             }
         }
 
-        let connectPromise = new Promise((resolve, reject) => {
+        // Guarded: close() rejects a pending connect() synchronously. See guardedPromise().
+        let connectPromise = guardedPromise((resolve, reject) => {
             // Whatever the proxy phase already used is gone from the budget
             this.connectTimeout = setTimeout(() => {
                 let err = deadline.error();
@@ -2533,10 +2513,6 @@ class ImapFlow extends EventEmitter {
             this.socket.on('error', this._connectErrorHandler);
         });
 
-        // Prevent unhandled promise rejection if close() rejects the connect
-        // promise synchronously. The rejection still propagates to the caller.
-        connectPromise.catch(noop);
-
         await connectPromise;
     }
 
@@ -2563,11 +2539,29 @@ class ImapFlow extends EventEmitter {
         setImmediate(() => this.close());
     }
 
-    // Builds the standard "connection not available" error, optionally annotated with the
-    // server's BYE reason. Single source of truth so every NoConnection rejection is consistent.
-    createNoConnectionError(byeReason) {
-        const error = new Error('Connection not available');
-        error.code = 'NoConnection';
+    // Builds an error describing a connection that is gone. Every such error is stamped here so
+    // the stamping cannot drift between sites: the connection id always travels on it, and each
+    // site names itself through `meta` (`rejectedFrom`, plus the command or mailbox path it
+    // belongs to).
+    //
+    // A stack trace only records where an error was built, and close() hands a rejection to every
+    // pending request and every queued lock in the same tick, so without these an error that
+    // reaches a global unhandledRejection handler arrives with nothing that identifies the
+    // connection it came from, let alone which of the rejected promises carried it.
+    createConnectionError(code, message, meta) {
+        const error = new Error(message);
+        error.code = code;
+        error.cid = this.id;
+        if (meta) {
+            Object.assign(error, meta);
+        }
+        return error;
+    }
+
+    // The standard "connection not available" error, optionally annotated with the server's BYE
+    // reason. Single source of truth so every NoConnection rejection is consistent.
+    createNoConnectionError(byeReason, meta) {
+        const error = this.createConnectionError('NoConnection', 'Connection not available', meta);
         if (byeReason) {
             error.reason = byeReason;
         }
@@ -2612,9 +2606,7 @@ class ImapFlow extends EventEmitter {
             if (typeof this._upgradeReject === 'function') {
                 let reject = this._upgradeReject;
                 this._upgradeReject = null;
-                let err = new Error('Connection closed during TLS upgrade');
-                err.code = 'NoConnection';
-                reject(err);
+                reject(this.createNoConnectionError(false, { rejectedFrom: 'upgrade' }));
             }
 
             if (typeof this.initialReject === 'function' && !this.options.verifyOnly) {
@@ -2630,9 +2622,9 @@ class ImapFlow extends EventEmitter {
                 if (this.byeReason) {
                     err.reason = this.byeReason;
                 }
-                // Synchronous rejection is safe: connectPromise.catch(noop) is already
-                // attached, so the rejection is observed immediately. close() is synchronous,
-                // so all cleanup completes before any microtask rejection handler runs.
+                // Synchronous rejection is safe: connectPromise was built by guardedPromise(),
+                // so the rejection is already observed. close() is synchronous, so all cleanup
+                // completes before any microtask rejection handler runs.
                 reject(err);
             }
 
@@ -2690,18 +2682,14 @@ class ImapFlow extends EventEmitter {
                 }
             }
 
-            // Helper to create connection error (delegates to the shared builder)
-            const createNoConnectionError = byeReason => this.createNoConnectionError(byeReason);
-
-            // Reject pending requests and locks synchronously. Each exec() and
-            // getMailboxLock() promise already has .catch(noop) attached, so the
-            // rejection is observed immediately and will not trigger
-            // unhandledRejection. close() is synchronous, so all remaining cleanup
-            // runs before any microtask rejection handler fires.
+            // Reject pending requests and locks synchronously. Every promise rejected here was
+            // built by guardedPromise(), so its rejection is already observed and cannot trigger
+            // unhandledRejection. close() is synchronous, so all remaining cleanup runs before
+            // any microtask rejection handler fires.
             let byeReason = this.byeReason;
 
             for (let request of pendingRequests) {
-                request.reject(createNoConnectionError(byeReason));
+                request.reject(this.createNoConnectionError(byeReason, { rejectedFrom: 'pendingRequest', command: request.command }));
             }
 
             // Clear current lock - holder will see errors when they try operations.
@@ -2720,7 +2708,7 @@ class ImapFlow extends EventEmitter {
                         lock.acquireTimer = null;
                     }
                     if (typeof lock.reject === 'function') {
-                        lock.reject(createNoConnectionError(byeReason));
+                        lock.reject(this.createNoConnectionError(byeReason, { rejectedFrom: 'mailboxLock', path: lock.path }));
                     }
                 }
             }
@@ -2848,7 +2836,7 @@ class ImapFlow extends EventEmitter {
     /**
      * Returns current quota
      *
-     * @param {String} [path] Optional mailbox path if you want to check quota for specific folder
+     * @param {string|array} [path] Optional mailbox path if you want to check quota for specific folder. If value is an array then it is joined using current delimiter symbols. Namespace prefix is added automatically if required.
      * @returns {Promise<QuotaResponse|Boolean>} Quota information or `false` if QUOTA extension is not supported or requested path does not exist
      *
      * @example
@@ -3101,7 +3089,7 @@ class ImapFlow extends EventEmitter {
     /**
      * Requests the status of the indicated mailbox. Only requested status values will be returned.
      *
-     * @param {String} path mailbox path to check for (unicode string)
+     * @param {string|array} path mailbox path to check for (unicode string). If value is an array then it is joined using current delimiter symbols. Namespace prefix is added automatically if required.
      * @param {Object} query defines requested status items
      * @param {Boolean} query.messages if `true` request count of messages
      * @param {Boolean} query.recent if `true` request count of messages with \\Recent tag
@@ -3389,7 +3377,7 @@ class ImapFlow extends EventEmitter {
     /**
      * Appends a new message to a mailbox
      *
-     * @param {String} path Mailbox path to upload the message to (unicode string)
+     * @param {string|array} path Mailbox path to upload the message to (unicode string). If value is an array then it is joined using current delimiter symbols. Namespace prefix is added automatically if required.
      * @param {string|Buffer} content RFC822 formatted email message
      * @param {string[]} [flags] an array of flags to be set for the uploaded message
      * @param {Date|string} [idate=now] internal date to be set for the message
@@ -3415,7 +3403,7 @@ class ImapFlow extends EventEmitter {
      * Copies messages from current mailbox to destination mailbox
      *
      * @param {SequenceString | Number[] | SearchObject} range Range of messages to copy
-     * @param {String} destination Mailbox path to copy the messages to
+     * @param {string|array} destination Mailbox path to copy the messages to. If value is an array then it is joined using current delimiter symbols. Namespace prefix is added automatically if required.
      * @param {Object} [options]
      * @param {Boolean} [options.uid] If `true` then uses UID {@link SequenceString} instead of sequence numbers
      * @returns {Promise<CopyResponseObject>} info about copies messages
@@ -3439,7 +3427,7 @@ class ImapFlow extends EventEmitter {
      * Moves messages from current mailbox to destination mailbox
      *
      * @param {SequenceString | Number[] | SearchObject} range Range of messages to move
-     * @param {String} destination Mailbox path to move the messages to
+     * @param {string|array} destination Mailbox path to move the messages to. If value is an array then it is joined using current delimiter symbols. Namespace prefix is added automatically if required.
      * @param {Object} [options]
      * @param {Boolean} [options.uid] If `true` then uses UID {@link SequenceString} instead of sequence numbers
      * @returns {Promise<CopyResponseObject>} info about moved messages
@@ -3720,9 +3708,7 @@ class ImapFlow extends EventEmitter {
                 lastRes = res;
 
                 if (this.isClosed || !this.socket || this.socket.destroyed) {
-                    let error = new Error('Connection closed');
-                    error.code = 'EConnectionClosed';
-                    throw error;
+                    throw this.createConnectionError('EConnectionClosed', 'Connection closed', { rejectedFrom: 'fetchStream', command: 'FETCH' });
                 }
 
                 yield res.response;
@@ -4427,7 +4413,7 @@ class ImapFlow extends EventEmitter {
         }
 
         if (!this.socket || this.socket.destroyed) {
-            throw this.createNoConnectionError();
+            throw this.createNoConnectionError(false, { rejectedFrom: 'noSocket', command });
         }
 
         clearTimeout(this.idleStartTimer);
@@ -4470,7 +4456,7 @@ class ImapFlow extends EventEmitter {
         }
 
         if (!this.socket || this.socket.destroyed) {
-            throw this.createNoConnectionError();
+            throw this.createNoConnectionError(false, { rejectedFrom: 'noSocket', command });
         }
 
         let handler = this.commands.get(command);
@@ -4587,9 +4573,7 @@ class ImapFlow extends EventEmitter {
 
                 if (!this.usable || !this.socket || this.socket.destroyed) {
                     this.log.trace({ msg: 'Failed to acquire mailbox lock', path, lockId, idling: this.idling });
-                    let error = new Error('Connection not available');
-                    error.code = 'NoConnection';
-                    reject(error);
+                    reject(this.createNoConnectionError(false, { rejectedFrom: 'mailboxLock', path }));
                     continue; // Process next lock in queue
                 }
 
@@ -4713,7 +4697,8 @@ class ImapFlow extends EventEmitter {
                 : null
         });
 
-        let lockPromise = new Promise((resolve, reject) => {
+        // Guarded: close() rejects every queued lock synchronously. See guardedPromise().
+        let lockPromise = guardedPromise((resolve, reject) => {
             let lockEntry = { resolve, reject, path, options, lockId };
             this.locks.push(lockEntry);
 
@@ -4737,10 +4722,6 @@ class ImapFlow extends EventEmitter {
             this.processLocks().catch(err => reject(err));
         });
 
-        // Prevent unhandled promise rejection if close() rejects this lock
-        // synchronously. The rejection still propagates to the caller.
-        lockPromise.catch(noop);
-
         return lockPromise;
     }
 

package/lib/tools.js

@@ -69,7 +69,48 @@ class AuthenticationFailure extends Error {
     authenticationFailed = true;
 }
 
+// Deliberate no-op, used as the observer a guarded promise attaches to its own rejection.
+const noop = () => {};
+
 const tools = {
+    noop,
+
+    /**
+     * Creates a promise whose rejection is observed as soon as it exists.
+     *
+     * close() rejects every promise it owns - the in-flight and queued commands, the pending
+     * connect(), the queued mailbox locks, the waiters for an IDLE break - synchronously, from a
+     * socket event. A consumer that only reaches its `await` a microtask later has not attached a
+     * handler yet at the moment Node decides whether the rejection was observed, and the whole
+     * worker dies on the resulting unhandledRejection. The pre-attached observer settles that
+     * question; the rejection still propagates normally to whoever awaits the returned promise.
+     *
+     * Creation and guarding are one call because splitting them is what actually goes wrong: the
+     * guard was hand-attached at three of the four sites and the fourth (the IDLE-break waiter)
+     * went unguarded, on exactly the path a server BYE takes.
+     *
+     * @param {Function} executor - Promise executor, (resolve, reject) => {}
+     * @returns {Promise} The promise, with its rejection already observed
+     */
+    guardedPromise(executor) {
+        let promise = new Promise(executor);
+        promise.catch(noop);
+        return promise;
+    },
+
+    /**
+     * The already-rejected form of guardedPromise(), for a call that has to hand back a rejected
+     * promise rather than throw.
+     *
+     * @param {Error} error - Rejection reason
+     * @returns {Promise} Rejected promise, with its rejection already observed
+     */
+    guardedReject(error) {
+        let promise = Promise.reject(error);
+        promise.catch(noop);
+        return promise;
+    },
+
     /**
      * Detaches a background timer from the event loop, so it cannot keep the process alive on its
      * own. Applied to every background timer (auto-IDLE, IDLE restart, fallback polling, throttle
@@ -764,6 +805,17 @@ const tools = {
         return name;
     },
 
+    /**
+     * Decodes an ENVELOPE text field for display: encoded words first, then the
+     * surrounding quotes some servers leave in place.
+     *
+     * @param {String} value - Raw field value from an ENVELOPE response
+     * @returns {String} Decoded, unquoted text
+     */
+    decodeText(value) {
+        return tools.processName(libmime.decodeWords(value));
+    },
+
     /**
      * Parses a raw IMAP ENVELOPE response into a structured envelope object.
      *
@@ -795,14 +847,25 @@ const tools = {
                             // throwing on the dereference and dropping the message
                             return false;
                         }
-                        let address = (getStrValue(addr[2]) || '') + '@' + (getStrValue(addr[3]) || '');
-                        if (address === '@') {
-                            address = '';
+
+                        let name = tools.decodeText(getStrValue(addr[0]));
+                        let mailbox = getStrValue(addr[2]) || '';
+                        let host = getStrValue(addr[3]) || '';
+
+                        if (!host) {
+                            // RFC 9051 7.5.2: a NIL host field marks RFC 5322 group syntax, it is not
+                            // an empty domain. A non-NIL mailbox then holds the group name phrase, a
+                            // NIL one closes the group. Joining the fields anyway would invent an
+                            // address that never appeared in the message, eg. "undisclosed-recipients@",
+                            // so surface the group name as a display name and leave the address empty.
+                            // End-of-group markers carry neither and the filter below drops them.
+                            // The mirror case, a NIL mailbox with a host, is left alone on purpose:
+                            // the grammar gives it no meaning, so a server sending it is simply
+                            // malformed rather than signalling anything we could act on.
+                            return { name: name || (mailbox && tools.decodeText(mailbox)), address: '' };
                         }
-                        return {
-                            name: tools.processName(libmime.decodeWords(getStrValue(addr[0]))),
-                            address
-                        };
+
+                        return { name, address: `${mailbox}@${host}` };
                     })
                     .filter(addr => addr && (addr.name || addr.address));
             },

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "imapflow",
-    "version": "1.7.1",
+    "version": "1.7.3",
     "description": "IMAP Client for Node",
     "main": "lib/imap-flow.js",
     "types": "lib/imap-flow.d.ts",
@@ -32,7 +32,7 @@
         "@eslint/js": "10.0.1",
         "@types/node": "26.2.0",
         "c8": "12.0.0",
-        "eslint": "10.8.1",
+        "eslint": "10.9.0",
         "eslint-config-nodemailer": "1.2.0",
         "eslint-config-prettier": "10.1.8",
         "grunt": "1.6.3",

package/test/fetch-generator-test.js

@@ -5,10 +5,12 @@ const { ImapFlow } = require('../lib/imap-flow');
 // Helper: create a minimal mock context with the fetch() generator bound to it.
 // The `run` override controls how untagged FETCH responses are delivered.
 const createFetchContext = runOverride => ({
+    id: 'test-cid',
     mailbox: { path: 'INBOX', exists: 10 },
     isClosed: false,
     socket: { destroyed: false },
     resolveRange: async range => range,
+    createConnectionError: ImapFlow.prototype.createConnectionError,
     run: runOverride
 });
 

package/test/imapflow-test.js

@@ -47,10 +47,12 @@ module.exports['Create imapflow instance with custom logger'] = async test => {
 // Helpers for testing prototype methods on a mock context
 // ---------------------------------------------------------------------------
 const createFetchContext = runOverride => ({
+    id: 'test-cid',
     mailbox: { path: 'INBOX', exists: 10 },
     isClosed: false,
     socket: { destroyed: false },
     resolveRange: async range => range,
+    createConnectionError: ImapFlow.prototype.createConnectionError,
     run: runOverride
 });
 

package/test/tools-test.js

@@ -716,6 +716,25 @@ module.exports['Tools: processName with short quoted'] = test => {
     test.done();
 };
 
+// ============================================
+// decodeText tests
+// ============================================
+
+module.exports['Tools: decodeText decodes encoded words and strips quotes'] = test => {
+    test.equal(tools.decodeText('=?utf-8?Q?T=C3=B5nu?='), 'Tõnu');
+    test.equal(tools.decodeText('"=?utf-8?Q?T=C3=B5nu?="'), 'Tõnu');
+    test.equal(tools.decodeText('Plain Name'), 'Plain Name');
+    test.done();
+};
+
+module.exports['Tools: decodeText tolerates missing values'] = test => {
+    // getStrValue returns false for a NIL envelope field
+    test.equal(tools.decodeText(false), '');
+    test.equal(tools.decodeText(null), '');
+    test.equal(tools.decodeText(undefined), '');
+    test.done();
+};
+
 // ============================================
 // getFolderTree tests
 // ============================================
@@ -885,6 +904,100 @@ module.exports['Tools: parseEnvelope with empty address parts'] = test => {
     test.done();
 };
 
+module.exports['Tools: parseEnvelope keeps group syntax out of the address'] = test => {
+    // RFC 9051 7.5.2: a NIL host marks group syntax, so "undisclosed-recipients:;" must
+    // not turn into the invented address "undisclosed-recipients@"
+    let entry = [
+        null, // date
+        null, // subject
+        [], // from
+        [], // sender
+        [], // reply-to
+        [
+            [null, null, { value: 'undisclosed-recipients' }, null], // start of group
+            [null, null, null, null] // end of group
+        ], // to
+        [], // cc
+        [], // bcc
+        null, // in-reply-to
+        null // message-id
+    ];
+
+    let result = tools.parseEnvelope(entry);
+    // The end-of-group marker carries neither name nor address and is dropped
+    test.deepEqual(result.to, [{ name: 'undisclosed-recipients', address: '' }]);
+    test.done();
+};
+
+module.exports['Tools: parseEnvelope keeps group members alongside the markers'] = test => {
+    let entry = [
+        null, // date
+        null, // subject
+        [], // from
+        [], // sender
+        [], // reply-to
+        [
+            [null, null, { value: 'Team' }, null], // start of group
+            [{ value: 'Member One' }, null, { value: 'one' }, { value: 'example.com' }],
+            [{ value: 'Member Two' }, null, { value: 'two' }, { value: 'example.com' }],
+            [null, null, null, null] // end of group
+        ], // to
+        [], // cc
+        [], // bcc
+        null, // in-reply-to
+        null // message-id
+    ];
+
+    let result = tools.parseEnvelope(entry);
+    test.deepEqual(result.to, [
+        { name: 'Team', address: '' },
+        { name: 'Member One', address: 'one@example.com' },
+        { name: 'Member Two', address: 'two@example.com' }
+    ]);
+    test.done();
+};
+
+module.exports['Tools: parseEnvelope does not join a NIL host onto a mailbox'] = test => {
+    // Some servers parse a malformed header such as
+    // "To: user@example.com user@example.com" into a personal name plus a mailbox
+    // with a NIL host. Joining those produced the invalid address "example.com@".
+    let entry = [
+        null, // date
+        null, // subject
+        [], // from
+        [], // sender
+        [], // reply-to
+        [[{ value: 'user@example.com user@' }, null, { value: 'example.com' }, null]], // to
+        [], // cc
+        [], // bcc
+        null, // in-reply-to
+        null // message-id
+    ];
+
+    let result = tools.parseEnvelope(entry);
+    test.deepEqual(result.to, [{ name: 'user@example.com user@', address: '' }]);
+    test.done();
+};
+
+module.exports['Tools: parseEnvelope decodes an encoded group name'] = test => {
+    let entry = [
+        null, // date
+        null, // subject
+        [], // from
+        [], // sender
+        [], // reply-to
+        [[null, null, { value: '=?utf-8?Q?T=C3=B5ny?=' }, null]], // to
+        [], // cc
+        [], // bcc
+        null, // in-reply-to
+        null // message-id
+    ];
+
+    let result = tools.parseEnvelope(entry);
+    test.deepEqual(result.to, [{ name: 'Tõny', address: '' }]);
+    test.done();
+};
+
 // ============================================
 // getStructuredParams tests
 // ============================================

package/test/unhandled-rejection-test.js

@@ -408,6 +408,98 @@ exports['Unhandled Rejection Prevention'] = {
         });
     },
 
+    'close() stamps the rejection site, command and connection id on the error'(test) {
+        test.expect(5);
+
+        const client = new ImapFlow({
+            host: '127.0.0.1',
+            port: 1,
+            secure: false,
+            logger: false,
+            id: 'test-cid'
+        });
+
+        client.state = client.states.AUTHENTICATED;
+        client.socket = new net.Socket();
+
+        const detector = installRejectionDetector(test);
+
+        let promise = client.exec('NOOP');
+        client.close();
+
+        setTimeout(() => {
+            detector.check();
+            promise.catch(err => {
+                test.equal(err.code, 'NoConnection', 'caller should receive NoConnection error');
+                test.equal(err.rejectedFrom, 'pendingRequest', 'error should name the rejection site');
+                test.equal(err.command, 'NOOP', 'error should name the command it belonged to');
+                test.equal(err.cid, 'test-cid', 'error should carry the connection id');
+                test.done();
+            });
+        }, 100);
+    },
+
+    'preCheck() waiter rejected by close() should not cause unhandled rejection'(test) {
+        test.expect(2);
+
+        // Never acknowledge IDLE with a "+" continuation. preCheck() can only send DONE once
+        // the server has acknowledged, so its waiter stays queued until close() tears the
+        // IDLE command down and runIdle() rejects everything still waiting.
+        const server = createMockServer({
+            extraCapabilities: 'IDLE',
+            onCommand(socket, tag, command) {
+                if (command === 'IDLE') {
+                    return true;
+                }
+            }
+        });
+
+        server.listen(0, '127.0.0.1', async () => {
+            const port = server.address().port;
+
+            const client = new ImapFlow({
+                host: '127.0.0.1',
+                port,
+                secure: false,
+                logger: false,
+                disableAutoIdle: true,
+                auth: {
+                    user: 'test',
+                    pass: 'test'
+                }
+            });
+
+            const detector = installRejectionDetector(test);
+
+            try {
+                await client.connect();
+                await client.mailboxOpen('INBOX');
+
+                client.idle().catch(() => {
+                    // Expected: IDLE rejects when the connection is closed
+                });
+
+                // Let the IDLE command reach the server and install preCheck()
+                await new Promise(r => setTimeout(r, 100));
+                test.equal(typeof client.preCheck, 'function', 'IDLE should have installed preCheck()');
+
+                // Request an IDLE break and drop the returned promise on the floor, so the
+                // queued waiter has no handler of its own when close() rejects it
+                client.preCheck();
+
+                client.close();
+
+                await new Promise(r => setTimeout(r, 100));
+                detector.check();
+            } catch (err) {
+                detector.check();
+                test.ok(false, 'Unexpected error: ' + err.message);
+            } finally {
+                server.close(() => test.done());
+            }
+        });
+    },
+
     'BAD response to FETCH should not cause unhandled rejection (Death 2)'(test) {
         test.expect(3);