imapflow 2.2.1 → 2.2.2

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [2.2.2](https://github.com/postalsys/imapflow/compare/v2.2.1...v2.2.2) (2026-10-03)
+
+
+### Bug Fixes
+
+* do not let a flag update that reduces to nothing clear every flag ([686a04b](https://github.com/postalsys/imapflow/commit/686a04b6c29d5f97afdbb03779e7b29d102cdef3))
+* keep append flags when the destination is not an open read-write mailbox ([d7f8da3](https://github.com/postalsys/imapflow/commit/d7f8da3131d8df5b5607021dbbca27445bb973c2)), closes [#415](https://github.com/postalsys/imapflow/issues/415)
+
 ## [2.2.1](https://github.com/postalsys/imapflow/compare/v2.2.0...v2.2.1) (2026-10-01)
 
 

package/dist/cjs/commands/append.js

@@ -37,10 +37,34 @@ async function append(connection, destination, content, flags, idate) {
     let selected = (0, tools_js_1.getSelectedMailbox)(connection);
     // The selected mailbox when appending to it, false otherwise
     const targetMailbox = selected && (0, tools_js_1.comparePaths)(connection, selected.path, destination) ? selected : false;
-    // Validate and format flags. Only flags allowed by the mailbox's permanentFlags are included.
+    // Flags are only filtered when a read-write selection of the destination itself says what it
+    // accepts: the permanentFlags of an unrelated mailbox say nothing about the destination, and a
+    // read-only selection reports an empty PERMANENTFLAGS list (Dovecot does), which canUseFlag()
+    // reads as deny-all. Otherwise they go to the server unfiltered and it decides (RFC 9051).
+    const flagSource = targetMailbox && !targetMailbox.readOnly ? targetMailbox : false;
+    const dropped = [];
     flags = (Array.isArray(flags) ? flags : [].concat(flags || []))
-        .map(flag => flag && (0, tools_js_1.formatFlag)(flag.toString()))
-        .filter((flag) => !!flag && (0, tools_js_1.canUseFlag)(connection.mailbox, flag));
+        .map(flag => {
+        const formatted = flag && (0, tools_js_1.formatFlag)(flag.toString());
+        if (!formatted || !(0, tools_js_1.canUseFlag)(flagSource, formatted)) {
+            if (flag) {
+                dropped.push(flag.toString());
+            }
+            return false;
+        }
+        return formatted;
+    })
+        .filter((flag) => !!flag);
+    // The stored message simply ends up without them, and the caller is told nothing, so leave
+    // a trail for the flags that never reached the server.
+    if (dropped.length) {
+        connection.log.warn({
+            msg: 'Dropped flags the mailbox does not accept',
+            cid: connection.id,
+            path: destination,
+            dropped
+        });
+    }
     // APPEND command format: APPEND <mailbox> [<flags>] [<date-time>] <literal>
     let attributes = [{ type: 'ATOM', value: (0, tools_js_1.encodePath)(connection, destination) }];
     // Internal date: the date the server should record for this message.

package/dist/cjs/commands/store.js

@@ -31,8 +31,11 @@ async function store(connection, range, flags, options) {
     else if (options.silent) {
         operation = `${operation}.SILENT`;
     }
+    // Normalized once: the raw value is also compared below, and a mixed-case 'SET' must not
+    // take the set branch here and the add branch there.
+    const operationName = (options.operation || '').toLowerCase();
     // Prefix determines the operation: none = set (replace), + = add, - = remove
-    switch ((options.operation || '').toLowerCase()) {
+    switch (operationName) {
         case 'set':
             break;
         case 'remove':
@@ -43,20 +46,42 @@ async function store(connection, range, flags, options) {
             operation = `+${operation}`;
             break;
     }
-    // Validate each flag: format it (normalize backslash prefix for system flags),
-    // then check if the mailbox's permanentFlags allow it. Removal is always allowed
+    // Only an explicitly empty array asks for every flag to be cleared. A missing value is not
+    // that request, and neither is a 'set' whose flags all get dropped below: either would
+    // compile to "FLAGS ()" and wipe the message instead of storing what was asked for. The
+    // line is drawn at destroying flags, not at fidelity, so a set that keeps some of the
+    // requested flags still runs, as the documented contract for those methods says.
+    const clearAll = operationName === 'set' && Array.isArray(flags) && !flags.length;
+    // permanentFlags lists the IMAP keywords the mailbox accepts and says nothing about Gmail
+    // labels, so it is not consulted for X-GM-LABELS - the same reason an unrelated mailbox's
+    // flags are not consulted for APPEND (issue #415).
+    const flagSource = options.useLabels ? false : mailbox;
+    // Validate each flag: format it (normalize backslash prefix for system flags, reject the
+    // server-owned \Recent), then check that the mailbox allows it. Removal is always allowed
     // since it doesn't require the flag to be in permanentFlags.
+    const dropped = [];
     flags = (Array.isArray(flags) ? flags : [].concat(flags || []))
         .map(flag => {
         let formatted = (0, tools_js_1.formatFlag)(flag);
-        if (!(0, tools_js_1.canUseFlag)(mailbox, formatted) && options.operation !== 'remove') {
+        if (!formatted || (!(0, tools_js_1.canUseFlag)(flagSource, formatted) && operationName !== 'remove')) {
+            dropped.push(flag);
             return false;
         }
         return formatted;
     })
         .filter((flag) => !!flag);
-    // Allow empty flags only for 'set' operation (which clears all flags)
-    if (!flags.length && options.operation !== 'set') {
+    // The caller is told nothing by the boolean this returns, so leave a trail for the flags
+    // that never reached the server.
+    if (dropped.length) {
+        connection.log.warn({
+            msg: 'Dropped flags the mailbox does not accept',
+            cid: connection.id,
+            path: mailbox.path,
+            operation,
+            dropped
+        });
+    }
+    if (!flags.length && !clearAll) {
         return false;
     }
     let attributes = [

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

@@ -356,7 +356,7 @@ export declare class ImapFlow extends EventEmitter {
      * Sets flags for a message or message range
      *
      * @param range Range to filter the messages
-     * @param flags Array of flags to set. Only flags that are permitted to set are used, other flags are ignored
+     * @param flags Array of flags to set. Only flags that are permitted to set are used, other flags are ignored. An empty array clears every flag, but a non-empty array with nothing usable in it is refused rather than clearing the message
      * @param options Store options
      * @returns Did the operation succeed or not
      *

package/dist/cjs/imap-flow.js

@@ -2631,7 +2631,7 @@ class ImapFlow extends node_events_1.EventEmitter {
      * Sets flags for a message or message range
      *
      * @param range Range to filter the messages
-     * @param flags Array of flags to set. Only flags that are permitted to set are used, other flags are ignored
+     * @param flags Array of flags to set. Only flags that are permitted to set are used, other flags are ignored. An empty array clears every flag, but a non-empty array with nothing usable in it is refused rather than clearing the message
      * @param options Store options
      * @returns Did the operation succeed or not
      *

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

@@ -1,3 +1,3 @@
 export declare const name = "imapflow";
-export declare const version = "2.2.1";
+export declare const version = "2.2.2";
 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.1";
+exports.version = "2.2.2";
 exports.homepage = "https://imapflow.com/";

package/dist/esm/commands/append.js

@@ -34,10 +34,34 @@ export default async function append(connection, destination, content, flags, id
     let selected = getSelectedMailbox(connection);
     // The selected mailbox when appending to it, false otherwise
     const targetMailbox = selected && comparePaths(connection, selected.path, destination) ? selected : false;
-    // Validate and format flags. Only flags allowed by the mailbox's permanentFlags are included.
+    // Flags are only filtered when a read-write selection of the destination itself says what it
+    // accepts: the permanentFlags of an unrelated mailbox say nothing about the destination, and a
+    // read-only selection reports an empty PERMANENTFLAGS list (Dovecot does), which canUseFlag()
+    // reads as deny-all. Otherwise they go to the server unfiltered and it decides (RFC 9051).
+    const flagSource = targetMailbox && !targetMailbox.readOnly ? targetMailbox : false;
+    const dropped = [];
     flags = (Array.isArray(flags) ? flags : [].concat(flags || []))
-        .map(flag => flag && formatFlag(flag.toString()))
-        .filter((flag) => !!flag && canUseFlag(connection.mailbox, flag));
+        .map(flag => {
+        const formatted = flag && formatFlag(flag.toString());
+        if (!formatted || !canUseFlag(flagSource, formatted)) {
+            if (flag) {
+                dropped.push(flag.toString());
+            }
+            return false;
+        }
+        return formatted;
+    })
+        .filter((flag) => !!flag);
+    // The stored message simply ends up without them, and the caller is told nothing, so leave
+    // a trail for the flags that never reached the server.
+    if (dropped.length) {
+        connection.log.warn({
+            msg: 'Dropped flags the mailbox does not accept',
+            cid: connection.id,
+            path: destination,
+            dropped
+        });
+    }
     // APPEND command format: APPEND <mailbox> [<flags>] [<date-time>] <literal>
     let attributes = [{ type: 'ATOM', value: encodePath(connection, destination) }];
     // Internal date: the date the server should record for this message.

package/dist/esm/commands/store.js

@@ -28,8 +28,11 @@ export default async function store(connection, range, flags, options) {
     else if (options.silent) {
         operation = `${operation}.SILENT`;
     }
+    // Normalized once: the raw value is also compared below, and a mixed-case 'SET' must not
+    // take the set branch here and the add branch there.
+    const operationName = (options.operation || '').toLowerCase();
     // Prefix determines the operation: none = set (replace), + = add, - = remove
-    switch ((options.operation || '').toLowerCase()) {
+    switch (operationName) {
         case 'set':
             break;
         case 'remove':
@@ -40,20 +43,42 @@ export default async function store(connection, range, flags, options) {
             operation = `+${operation}`;
             break;
     }
-    // Validate each flag: format it (normalize backslash prefix for system flags),
-    // then check if the mailbox's permanentFlags allow it. Removal is always allowed
+    // Only an explicitly empty array asks for every flag to be cleared. A missing value is not
+    // that request, and neither is a 'set' whose flags all get dropped below: either would
+    // compile to "FLAGS ()" and wipe the message instead of storing what was asked for. The
+    // line is drawn at destroying flags, not at fidelity, so a set that keeps some of the
+    // requested flags still runs, as the documented contract for those methods says.
+    const clearAll = operationName === 'set' && Array.isArray(flags) && !flags.length;
+    // permanentFlags lists the IMAP keywords the mailbox accepts and says nothing about Gmail
+    // labels, so it is not consulted for X-GM-LABELS - the same reason an unrelated mailbox's
+    // flags are not consulted for APPEND (issue #415).
+    const flagSource = options.useLabels ? false : mailbox;
+    // Validate each flag: format it (normalize backslash prefix for system flags, reject the
+    // server-owned \Recent), then check that the mailbox allows it. Removal is always allowed
     // since it doesn't require the flag to be in permanentFlags.
+    const dropped = [];
     flags = (Array.isArray(flags) ? flags : [].concat(flags || []))
         .map(flag => {
         let formatted = formatFlag(flag);
-        if (!canUseFlag(mailbox, formatted) && options.operation !== 'remove') {
+        if (!formatted || (!canUseFlag(flagSource, formatted) && operationName !== 'remove')) {
+            dropped.push(flag);
             return false;
         }
         return formatted;
     })
         .filter((flag) => !!flag);
-    // Allow empty flags only for 'set' operation (which clears all flags)
-    if (!flags.length && options.operation !== 'set') {
+    // The caller is told nothing by the boolean this returns, so leave a trail for the flags
+    // that never reached the server.
+    if (dropped.length) {
+        connection.log.warn({
+            msg: 'Dropped flags the mailbox does not accept',
+            cid: connection.id,
+            path: mailbox.path,
+            operation,
+            dropped
+        });
+    }
+    if (!flags.length && !clearAll) {
         return false;
     }
     let attributes = [

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

@@ -356,7 +356,7 @@ export declare class ImapFlow extends EventEmitter {
      * Sets flags for a message or message range
      *
      * @param range Range to filter the messages
-     * @param flags Array of flags to set. Only flags that are permitted to set are used, other flags are ignored
+     * @param flags Array of flags to set. Only flags that are permitted to set are used, other flags are ignored. An empty array clears every flag, but a non-empty array with nothing usable in it is refused rather than clearing the message
      * @param options Store options
      * @returns Did the operation succeed or not
      *

package/dist/esm/imap-flow.js

@@ -2590,7 +2590,7 @@ export class ImapFlow extends EventEmitter {
      * Sets flags for a message or message range
      *
      * @param range Range to filter the messages
-     * @param flags Array of flags to set. Only flags that are permitted to set are used, other flags are ignored
+     * @param flags Array of flags to set. Only flags that are permitted to set are used, other flags are ignored. An empty array clears every flag, but a non-empty array with nothing usable in it is refused rather than clearing the message
      * @param options Store options
      * @returns Did the operation succeed or not
      *

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

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

package/dist/esm/package-info.js

@@ -1,4 +1,4 @@
 // Generated by scripts/build.js from package.json. Do not edit by hand.
 export const name = "imapflow";
-export const version = "2.2.1";
+export const version = "2.2.2";
 export const homepage = "https://imapflow.com/";

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "imapflow",
-    "version": "2.2.1",
+    "version": "2.2.2",
     "description": "IMAP Client for Node",
     "type": "module",
     "main": "./dist/cjs/imap-flow.js",
@@ -70,7 +70,7 @@
     "devDependencies": {
         "@types/node": "20.19.43",
         "c8": "12.0.0",
-        "eslint": "10.11.0",
+        "eslint": "10.12.0",
         "eslint-config-prettier": "10.1.8",
         "globals": "17.13.0",
         "prettier": "3.9.9",
@@ -78,7 +78,7 @@
         "types-node-legacy": "npm:@types/node@20.0.0",
         "typescript": "6.0.3",
         "typescript-eslint": "8.71.0",
-        "wrangler": "4.145.0"
+        "wrangler": "4.147.0"
     },
     "dependencies": {
         "@zone-eu/mailsplit": "5.4.19",
@@ -87,7 +87,7 @@
         "libbase64": "1.3.1",
         "libmime": "5.4.6",
         "libqp": "2.1.2",
-        "pino": "10.3.1",
+        "pino": "10.4.0",
         "socks": "2.8.10"
     },
     "engines": {