imapflow 1.7.1 → 1.7.2

package/.release-please-manifest.json

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

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [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/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

@@ -2848,7 +2848,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 +3101,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 +3389,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 +3415,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 +3439,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

package/lib/tools.js

@@ -764,6 +764,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 +806,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.2",
     "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/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
 // ============================================