imapflow 2.2.7 → 2.2.9

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## [2.2.9](https://github.com/postalsys/imapflow/compare/v2.2.8...v2.2.9) (2026-10-07)
+
+
+### Bug Fixes
+
+* declare DownloadOptions.binary, the QRESYNC mailboxOpen options and FetchQueryObject.emailId ([2ae26e6](https://github.com/postalsys/imapflow/commit/2ae26e64c39c83ac3e04a67e9d4d808a1258c55b))
+
+## [2.2.8](https://github.com/postalsys/imapflow/compare/v2.2.7...v2.2.8) (2026-10-07)
+
+
+### Bug Fixes
+
+* decrement mailbox.exists on untagged VANISHED (RFC 7162 section 3.2.10) ([b40cea2](https://github.com/postalsys/imapflow/commit/b40cea22d19edd10428fe1cda98115c2f8b6cd7a))
+* do not send sequence sets to an empty mailbox ([b40cea2](https://github.com/postalsys/imapflow/commit/b40cea22d19edd10428fe1cda98115c2f8b6cd7a))
+* drop flags and keywords that are not atoms instead of sending them quoted ([b40cea2](https://github.com/postalsys/imapflow/commit/b40cea22d19edd10428fe1cda98115c2f8b6cd7a))
+* encode and decode non-ASCII Gmail labels as modified UTF-7 like mailbox names ([b40cea2](https://github.com/postalsys/imapflow/commit/b40cea22d19edd10428fe1cda98115c2f8b6cd7a))
+* expand the FETCH ALL, FAST and FULL macros instead of sending them in a list ([b40cea2](https://github.com/postalsys/imapflow/commit/b40cea22d19edd10428fe1cda98115c2f8b6cd7a))
+* leave servername out of tls.connect() for IP literal hosts, which Bun rejects ([b40cea2](https://github.com/postalsys/imapflow/commit/b40cea22d19edd10428fe1cda98115c2f8b6cd7a))
+* refetch body sections Apache James drops, check FETCH answers belong to the download, enable CONDSTORE with QRESYNC ([6973263](https://github.com/postalsys/imapflow/commit/697326393a4a66e743822d7fb0ac045454458492))
+* send the OAuth token after the continuation request when SASL-IR is not advertised ([b40cea2](https://github.com/postalsys/imapflow/commit/b40cea22d19edd10428fe1cda98115c2f8b6cd7a))
+* send the STORE UNCHANGEDSINCE modifier before the flags (RFC 7162 section 3.1.3) ([b40cea2](https://github.com/postalsys/imapflow/commit/b40cea22d19edd10428fe1cda98115c2f8b6cd7a))
+
 ## [2.2.7](https://github.com/postalsys/imapflow/compare/v2.2.6...v2.2.7) (2026-10-07)
 
 

package/dist/cjs/commands/authenticate.js

@@ -66,15 +66,26 @@ async function authOauth(connection, username, accessToken) {
         // Empty breaker: XOAUTH2 expects an empty response to abort the SASL exchange
         breaker = '';
     }
+    let encoded = Buffer.from(oauthbearer).toString('base64');
+    // Without SASL-IR the payload may not ride on the command line (RFC 4959 section 3): it is
+    // sent as the answer to the first, empty continuation request instead
+    let payloadPending = !connection.capabilities.has('SASL-IR');
     let errorResponse = false;
     try {
-        let response = await connection.exec('AUTHENTICATE', [
-            { type: 'ATOM', value: command },
-            { type: 'ATOM', value: Buffer.from(oauthbearer).toString('base64'), sensitive: true }
-        ], {
+        let attributes = [{ type: 'ATOM', value: command }];
+        if (!payloadPending) {
+            attributes.push({ type: 'ATOM', value: encoded, sensitive: true });
+        }
+        let response = await connection.exec('AUTHENTICATE', attributes, {
             // Server sends a "+" continuation if auth fails, with a base64 JSON error payload.
             // We decode it for diagnostics, then send the breaker to terminate the exchange.
             onPlusTag: async (resp) => {
+                if (payloadPending) {
+                    payloadPending = false;
+                    connection.log.debug({ src: 'c', msg: '(* value hidden *)', comment: `Encoded response for AUTH=${command}`, cid: connection.id });
+                    connection.write(encoded);
+                    return;
+                }
                 if (resp.attributes && resp.attributes[0] && resp.attributes[0].type === 'TEXT') {
                     try {
                         errorResponse = JSON.parse(Buffer.from(resp.attributes[0].value, 'base64').toString());

package/dist/cjs/commands/enable.js

@@ -49,6 +49,12 @@ async function enable(connection, extensionList) {
         // extensions enabled by this command (RFC 5161), so a replace would drop
         // grants from an earlier ENABLE call
         connection.enabled = new Set([...connection.enabled, ...enabled]);
+        if (connection.enabled.has('QRESYNC')) {
+            // ENABLE QRESYNC is a CONDSTORE enabling command (RFC 7162 3.2.3), whether or not the
+            // server lists CONDSTORE in its ENABLED answer. Apache James advertises only QRESYNC
+            // and leaves a lone ENABLE CONDSTORE unanswered, which the RFC allows.
+            connection.enabled.add('CONDSTORE');
+        }
         response.next();
         return connection.enabled;
     }

package/dist/cjs/commands/fetch.js

@@ -65,13 +65,30 @@ async function fetch(connection, range, query, options) {
                 };
                 queryStructure.push(bodyPeek);
             };
-            // IMAP fetch macros (ALL, FAST, FULL) and standard data items map directly to IMAP atoms
-            ['all', 'fast', 'full', 'uid', 'flags', 'bodyStructure', 'envelope', 'internalDate'].forEach(key => {
-                if (query[key]) {
+            // The ALL, FAST and FULL macros may only be sent on their own, never in a list with other
+            // items (RFC 3501 section 9), and UID is always in the list, so they are expanded into
+            // the items they stand for. FULL is expanded to BODYSTRUCTURE rather than the
+            // non-extensible BODY, as documented for the full option.
+            let full = !!query.full;
+            let all = !!query.all || full;
+            let fast = !!query.fast || all;
+            let items = {
+                flags: query.flags || fast,
+                internalDate: query.internalDate || fast,
+                size: query.size || fast,
+                envelope: query.envelope || all,
+                bodyStructure: query.bodyStructure || full
+            };
+            // standard data items map directly to IMAP atoms
+            if (query.uid) {
+                queryStructure.push({ type: 'ATOM', value: 'UID' });
+            }
+            ['flags', 'bodyStructure', 'envelope', 'internalDate'].forEach(key => {
+                if (items[key]) {
                     queryStructure.push({ type: 'ATOM', value: key.toUpperCase() });
                 }
             });
-            if (query.size) {
+            if (items.size) {
                 queryStructure.push({ type: 'ATOM', value: 'RFC822.SIZE' });
             }
             // Fetch full message source, optionally with byte range (start/maxLength)
@@ -194,7 +211,7 @@ async function fetch(connection, range, query, options) {
                         if (consumerError) {
                             return;
                         }
-                        let formatted = await (0, tools_js_1.formatMessageResponse)(untagged, mailbox, connection.idHashAlgorithm);
+                        let formatted = await (0, tools_js_1.formatMessageResponse)(untagged, mailbox, connection.idHashAlgorithm, connection);
                         if (typeof options.onUntaggedFetch === 'function') {
                             /* c8 ignore next */ // a UID FETCH row without its UID is a non-compliant server, so the seq fallback is not exercised
                             let key = options.uid ? formatted.uid || formatted.seq : formatted.seq;

package/dist/cjs/commands/select.d.ts

@@ -1,24 +1,13 @@
 import type { ImapFlow } from '../imap-flow.js';
 import type { MailboxObject, MailboxOpenOptions } from '../types.js';
-/**
- * Options for SELECT/EXAMINE: the public open options plus the QRESYNC resynchronization
- * parameters, which are only honored when the QRESYNC extension has been enabled
- */
-export interface SelectOptions extends MailboxOpenOptions {
-    /** QRESYNC modseq value to fetch changes since */
-    changedSince?: bigint | number | string | undefined;
-    /** QRESYNC UID validity value */
-    uidValidity?: bigint | number | string | undefined;
-}
+/** SELECT/EXAMINE options, the QRESYNC parameters are part of the public mailboxOpen() options */
+export type SelectOptions = MailboxOpenOptions;
 /**
  * Selects or examines a mailbox, making it the current mailbox for subsequent operations.
  *
  * @param connection - IMAP connection instance
  * @param path - Mailbox path to select
- * @param options - Select options
- * @param options.readOnly - If true, use EXAMINE instead of SELECT (read-only access)
- * @param options.changedSince - QRESYNC modseq value to fetch changes since
- * @param options.uidValidity - QRESYNC UID validity value
+ * @param options - Select options, see MailboxOpenOptions
  * @returns Mailbox info object with path, flags, exists, uidNext, uidValidity, highestModseq, etc., or undefined if preconditions not met
  * @throws If the SELECT/EXAMINE command fails
  */

package/dist/cjs/commands/select.js

@@ -51,10 +51,7 @@ const VALUED_RESPONSE_CODES = Object.assign(Object.create(null), {
  *
  * @param connection - IMAP connection instance
  * @param path - Mailbox path to select
- * @param options - Select options
- * @param options.readOnly - If true, use EXAMINE instead of SELECT (read-only access)
- * @param options.changedSince - QRESYNC modseq value to fetch changes since
- * @param options.uidValidity - QRESYNC UID validity value
+ * @param options - Select options, see MailboxOpenOptions
  * @returns Mailbox info object with path, flags, exists, uidNext, uidValidity, highestModseq, etc., or undefined if preconditions not met
  * @throws If the SELECT/EXAMINE command fails
  */

package/dist/cjs/commands/store.js

@@ -61,7 +61,10 @@ async function store(connection, range, flags, options) {
     const dropped = [];
     flags = (Array.isArray(flags) ? flags : [].concat(flags || []))
         .map(flag => {
-        let formatted = (0, tools_js_1.formatFlag)(flag);
+        // Gmail labels other than the \-prefixed system labels are mailbox names: astrings in
+        // the form mailbox names take on the session (modified UTF-7 unless UTF-8 is enabled),
+        // not atoms like IMAP keywords
+        let formatted = options.useLabels && flag && flag.charAt(0) !== '\\' ? (0, tools_js_1.encodePath)(connection, flag) : (0, tools_js_1.formatFlag)(flag);
         if (!formatted || (!(0, tools_js_1.canUseFlag)(flagSource, formatted) && operationName !== 'remove')) {
             dropped.push(flag);
             return false;
@@ -83,13 +86,10 @@ async function store(connection, range, flags, options) {
     if (!flags.length && !clearAll) {
         return false;
     }
-    let attributes = [
-        { type: 'SEQUENCE', value: range },
-        { type: 'ATOM', value: operation },
-        flags.map(flag => ({ type: 'ATOM', value: flag }))
-    ];
+    let attributes = [{ type: 'SEQUENCE', value: range }];
     // CONDSTORE (RFC 7162): UNCHANGEDSINCE modifier prevents updating messages whose
     // mod-sequence is higher than the specified value, avoiding overwriting concurrent changes.
+    // The store-modifiers list goes between the sequence set and the item name (section 3.1.3).
     if (options.unchangedSince && connection.enabled.has('CONDSTORE') && !mailbox.noModseq) {
         attributes.push([
             {
@@ -102,6 +102,7 @@ async function store(connection, range, flags, options) {
             }
         ]);
     }
+    attributes.push({ type: 'ATOM', value: operation }, flags.map(flag => ({ type: 'ATOM', value: flag })));
     let response;
     try {
         response = await connection.exec(options.uid ? 'UID STORE' : 'STORE', attributes);

package/dist/cjs/download.js

@@ -19,6 +19,113 @@ const limited_passthrough_js_1 = require("./limited-passthrough.js");
 // away (a consumer destroying it closes it without a 'drain')
 const DRAIN_WAIT_EVENTS = ['drain', 'error', 'close'];
 const tools_js_1 = require("./tools.js");
+const isEmptySection = (value) => !value?.length;
+/**
+ * The section to ask again when exactly one of a part's MIME headers and content came back
+ * empty (see refetchDroppedSections()), undefined when both or neither did
+ */
+const droppedSection = (mime, content, mimeRequest, contentRequest) => {
+    if (isEmptySection(mime) === isEmptySection(content)) {
+        return undefined;
+    }
+    return isEmptySection(content) ? contentRequest : mimeRequest;
+};
+/** Start offset of every partial section among the requests, keyed by section */
+const partialStarts = (requests) => {
+    let starts = new Map();
+    for (let request of requests) {
+        if (typeof request !== 'string') {
+            starts.set(request.key, Number(request.start) || 0);
+        }
+    }
+    return starts;
+};
+// How many times a request is repeated after answers that belong to another request
+const MAX_FOREIGN_ANSWERS = 3;
+const requestedUid = (range, options) => options.uid && /^\d+$/.test(String(range)) ? Number(range) : undefined;
+const isForeignAnswer = (response, expected) => {
+    if (expected.uid && response.uid && response.uid !== expected.uid) {
+        return true;
+    }
+    for (let [key, start] of expected.origins) {
+        let origin = response.partialOrigins && response.partialOrigins.get(key);
+        // An answer without the origin is taken as is: some servers leave it out, and some
+        // ignore the partial specifier altogether
+        if (typeof origin === 'number' && origin !== start) {
+            return true;
+        }
+    }
+    return false;
+};
+/**
+ * fetchOne() that takes only an answer belonging to the request. Apache James now and then
+ * writes the head of a FETCH answer after its tagged OK, so the data of one request shows up
+ * within the answer to the next one. Taken at face value it would be the data of that next
+ * request, and a download would end without an error but with misplaced bytes. An answer for
+ * another UID, or with a partial section that starts at another offset than asked, is dropped
+ * and the request repeated.
+ */
+async function fetchExpected(client, range, query, options, expected) {
+    for (let attempt = 1;; attempt++) {
+        let response = await client.fetchOne(range, query, options);
+        if (!response || !isForeignAnswer(response, expected)) {
+            return response;
+        }
+        client.log.warn({
+            msg: 'Server answered with data of another request, asking again',
+            uid: response.uid,
+            origins: response.partialOrigins && Object.fromEntries(response.partialOrigins),
+            attempt,
+            cid: client.id
+        });
+        if (attempt >= MAX_FOREIGN_ANSWERS) {
+            let err = new Error('Server kept answering with data of another request');
+            err.code = 'DownloadIncomplete';
+            err.cid = client.id;
+            throw err;
+        }
+    }
+}
+/**
+ * Apache James (and the servers built on it, Twake Mail among them) answers only the first
+ * section it is asked for each MIME part of one FETCH and returns the other one empty:
+ * BODY[2.MIME] with BODY[2] yields the headers and a zero-length body, the reverse order loses
+ * the headers (FetchGroup.addPartContent() keeps the first descriptor for a part path). Asks the
+ * sections that came back empty again, in a FETCH of their own, and merges the answer into
+ * `response`. Callers only list a section whose companion did arrive, so a compliant server
+ * pays the extra round trip only for a part that really is empty.
+ */
+async function refetchDroppedSections(client, response, range, options, sections) {
+    if (!sections.length) {
+        return;
+    }
+    client.log.debug({
+        msg: 'Server answered a body section empty while its companion section was not, asking it again separately',
+        sections: sections.map(section => (typeof section === 'string' ? section : section.key)),
+        cid: client.id
+    });
+    // the UID pins the message even when the first command addressed it by sequence number
+    let uid = response.uid;
+    let retry = await fetchExpected(client, uid || range, { uid: true, bodyParts: sections }, uid ? { ...options, uid: true } : options, {
+        uid,
+        origins: partialStarts(sections)
+    });
+    if (!retry) {
+        return;
+    }
+    if (retry.headers) {
+        response.headers = retry.headers;
+    }
+    for (let [key, value] of retry.bodyParts || []) {
+        (response.bodyParts ??= new Map()).set(key, value);
+        if (retry.binaryParts && retry.binaryParts.has(key)) {
+            (response.binaryParts ??= new Set()).add(key);
+        }
+        else if (response.binaryParts) {
+            response.binaryParts.delete(key);
+        }
+    }
+}
 /**
  * Implements ImapFlow.download(), see its documentation
  *
@@ -66,6 +173,7 @@ async function downloadMessage(client, range, part, options) {
     let getNextPart = async (query) => {
         query = query || {};
         let mimeKey;
+        let contentRequest;
         if (!part) {
             query.source = {
                 start: processed,
@@ -88,13 +196,18 @@ async function downloadMessage(client, range, part, options) {
                     query.bodyParts.push(mimeKey);
                 }
             }
-            query.bodyParts.push({
+            contentRequest = {
                 key: part,
                 start: processed,
                 maxLength: chunkSize
-            });
+            };
+            query.bodyParts.push(contentRequest);
         }
-        let response = await client.fetchOne(range, query, downloadOptions);
+        let expected = {
+            uid: uid || requestedUid(range, downloadOptions),
+            origins: new Map([[part || '', processed]])
+        };
+        let response = await fetchExpected(client, range, query, downloadOptions, expected);
         if (!response) {
             return { response: false, chunk: false };
         }
@@ -104,6 +217,12 @@ async function downloadMessage(client, range, part, options) {
             range = uid;
             downloadOptions.uid = true;
         }
+        if (mimeKey && contentRequest) {
+            let dropped = droppedSection(mimeKey === 'header' ? response.headers : response.bodyParts?.get(mimeKey), response.bodyParts?.get(part), mimeKey, contentRequest);
+            if (dropped) {
+                await refetchDroppedSections(client, response, range, downloadOptions, [dropped]);
+            }
+        }
         let chunk = !part ? response.source : response.bodyParts && response.bodyParts.get(part);
         if (!chunk) {
             return {};
@@ -458,16 +577,31 @@ async function downloadMessageParts(client, range, parts, options) {
     // again on the answer for servers that ignore the partial specifier
     let maxBytes = (0, limited_passthrough_js_1.normalizeByteLimit)(downloadOptions.maxBytes);
     let query = { bodyParts: [] };
+    let contentRequests = new Map();
     for (let part of parts) {
         query.bodyParts.push(part + '.mime');
         // The partial specifier carries a 32-bit length (RFC 9051 "number"), so a cap beyond
         // that is applied on the answer alone
-        query.bodyParts.push(maxBytes > 0xffffffff ? part : { key: part, start: 0, maxLength: maxBytes });
+        let contentRequest = maxBytes > 0xffffffff ? part : { key: part, start: 0, maxLength: maxBytes };
+        contentRequests.set(part, contentRequest);
+        query.bodyParts.push(contentRequest);
     }
-    let response = await client.fetchOne(range, query, downloadOptions);
+    let response = await fetchExpected(client, range, query, downloadOptions, {
+        uid: requestedUid(range, downloadOptions),
+        origins: partialStarts(query.bodyParts)
+    });
     if (!response || !response.bodyParts) {
         return {};
     }
+    let dropped = [];
+    for (let [part, contentRequest] of contentRequests) {
+        let section = droppedSection(response.bodyParts.get(part + '.mime'), response.bodyParts.get(part), part + '.mime', contentRequest);
+        if (section) {
+            dropped.push(section);
+        }
+    }
+    // Sections of different parts do not collide, so every dropped one fits in one FETCH
+    await refetchDroppedSections(client, response, range, downloadOptions, dropped);
     let data = {};
     for (let [part, content] of response.bodyParts) {
         let keyParts = part.split('.mime');

package/dist/cjs/imap-flow.d.ts

@@ -122,8 +122,8 @@ export declare class ImapFlow extends EventEmitter {
      */
     usable: boolean;
     /**
-     * Currently authenticated user or `false` if mailbox is not open
-     * or `true` if connection was authenticated by PREAUTH
+     * `true` once the connection is authenticated (by LOGIN, AUTHENTICATE or a PREAUTH greeting),
+     * `false` before that. The user name is in `options.auth.user`
      */
     authenticated: string | boolean;
     /**

package/dist/cjs/imap-flow.js

@@ -1500,9 +1500,8 @@ class ImapFlow extends node_events_1.EventEmitter {
                 // of the IP - accepting any "localhost" certificate for any IP-hosted
                 // server, and rejecting legitimate IP-SAN certificates.
                 host: this.host,
-                servername: this.servername,
                 port: this.port
-            }, this.options.tls || {});
+            }, this.tlsServername(), this.options.tls || {});
             this.clearSocketHandlers();
             let settled = false;
             // Single settlement path for the upgrade. Every terminal outcome - handshake
@@ -1892,12 +1891,18 @@ class ImapFlow extends node_events_1.EventEmitter {
             uids = untagged.attributes[0].value;
         }
         let uidList = (0, tools_js_1.expandRange)(uids);
+        let earlier = tags.includes('EARLIER');
+        // RFC 7162 section 3.2.10: unlike VANISHED (EARLIER), a plain VANISHED reports messages the
+        // client knows about and decrements the message count like the same number of EXPUNGEs would
+        if (!earlier) {
+            mailbox.exists = Math.max(0, mailbox.exists - uidList.length);
+        }
         for (let uid of uidList) {
             let payload = {
                 path: mailbox.path,
                 uid,
                 vanished: true,
-                earlier: tags.includes('EARLIER')
+                earlier
             };
             await this.notifyExpunge(payload);
         }
@@ -1909,7 +1914,7 @@ class ImapFlow extends node_events_1.EventEmitter {
             // mailbox closed, ignore
             return;
         }
-        let message = await (0, tools_js_1.formatMessageResponse)(untagged, mailbox, this.idHashAlgorithm);
+        let message = await (0, tools_js_1.formatMessageResponse)(untagged, mailbox, this.idHashAlgorithm, this);
         if (message.flags) {
             let updateEvent = {
                 path: mailbox.path,
@@ -1938,6 +1943,12 @@ class ImapFlow extends node_events_1.EventEmitter {
         }
         return true;
     }
+    // servername for tls.connect(), left out for an IP literal host (this.servername is false then):
+    // Node treats a false value like a missing one, but Bun throws a TypeError for it
+    /** @internal */
+    tlsServername() {
+        return this.servername ? { servername: this.servername } : {};
+    }
     // Normalizes a message range from various input formats into an IMAP-compatible
     // sequence string (e.g., "1:5,7,10:*"). Handles: numbers, "*", {all:true},
     // {uid:value}, search query objects (resolved via SEARCH), and arrays of numbers.
@@ -1980,6 +1991,11 @@ class ImapFlow extends node_events_1.EventEmitter {
         if (!value) {
             return false;
         }
+        // An empty mailbox has no message numbers: every sequence set, "1:*" included, would get a
+        // BAD (RFC 9051 section 9, seq-number). UID sets may point past the end, so they are sent.
+        if (!options.uid && this.mailbox && !this.mailbox.exists) {
+            return false;
+        }
         return value;
     }
     // The single definition of "the connection is not free". A held or queued mailbox lock, a
@@ -2049,9 +2065,8 @@ class ImapFlow extends node_events_1.EventEmitter {
         let connector = this.secureConnection ? node_tls_1.default : node_net_1.default;
         let opts = Object.assign({
             host: this.host,
-            servername: this.servername,
             port: this.port
-        }, this.options.tls || {});
+        }, this.tlsServername(), this.options.tls || {});
         this.untaggedHandlers.OK = (...args) => this.initialOK(...args);
         this.untaggedHandlers.BYE = (...args) => this.serverBye(...args);
         this.untaggedHandlers.PREAUTH = () => this.initialPREAUTH();

package/dist/cjs/package-info.d.ts

@@ -1,3 +1,3 @@
 export declare const name = "imapflow";
-export declare const version = "2.2.7";
+export declare const version = "2.2.9";
 export declare const homepage = "https://imapflow.com/";

package/dist/cjs/package-info.js

@@ -3,5 +3,5 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.homepage = exports.version = exports.name = void 0;
 exports.name = "imapflow";
-exports.version = "2.2.7";
+exports.version = "2.2.9";
 exports.homepage = "https://imapflow.com/";

package/dist/cjs/search-compiler.js

@@ -371,10 +371,13 @@ const searchCompiler = (connection, query) => {
                             fail('InvalidSearchQuery', `Search value for ${term.toLowerCase()} must be a string`);
                         }
                         let flag = (0, tools_js_1.formatFlag)(params[term]);
-                        // formatFlag() refuses \Recent, which is not a keyword. Dropping the
-                        // criterion would widen the search, so the query is refused instead
+                        // formatFlag() refuses \Recent, which is not a keyword, and values that are
+                        // not atoms. Dropping the criterion would widen the search, so the query is
+                        // refused instead
                         if (flag === false) {
-                            fail('InvalidSearchQuery', `${params[term]} can not be searched as a keyword, use the "recent" search key instead`);
+                            fail('InvalidSearchQuery', /^\\recent$/i.test(params[term])
+                                ? `${params[term]} can not be searched as a keyword, use the "recent" search key instead`
+                                : `${params[term]} is not a valid keyword`);
                         }
                         // Compiled even when the mailbox does not allow the keyword: the
                         // correct answer is then the empty set, which dropping the

package/dist/cjs/tools.d.ts

@@ -293,9 +293,10 @@ export declare function getColorFlags(color: string | null | undefined): {
  * @param untagged - Parsed untagged IMAP response
  * @param mailbox - Current mailbox state object
  * @param idHashAlgorithm - Hash for the fallback message id, `md5` unless the client was told otherwise
+ * @param connection - Connection the response arrived on, decodes Gmail labels like mailbox names
  * @returns Formatted message object with properties like seq, uid, flags, envelope, etc.
  */
-export declare function formatMessageResponse(untagged: ImapResponse, mailbox: MailboxObject, idHashAlgorithm?: string): Promise<FetchMessageObject>;
+export declare function formatMessageResponse(untagged: ImapResponse, mailbox: MailboxObject, idHashAlgorithm?: string, connection?: ImapFlow): Promise<FetchMessageObject>;
 /**
  * Strips surrounding double quotes from a name string.
  *
@@ -364,8 +365,8 @@ export declare function formatDate(value: unknown): string | undefined;
  */
 export declare function formatDateTime(value: unknown): string | undefined;
 /**
- * Normalizes a flag string. Returns false for non-settable flags (e.g. \Recent),
- * and capitalizes system flags properly.
+ * Normalizes a flag string. Returns false for non-settable flags (e.g. \Recent) and for
+ * values that are not valid flags (keywords must be atoms), and capitalizes system flags properly.
  *
  * @param flag - Flag string to normalize
  * @returns Normalized flag string, or false if the flag cannot be set