nodemailer 10.0.11 → 10.0.13

package/dist/cjs/smtp-connection/index.js

@@ -104,8 +104,8 @@ function isPartialLine(line) {
  *  * **port** - is the port to connect to (defaults to 587 or 465)
  *  * **host** - is the hostname or IP address to connect to (defaults to 'localhost')
  *  * **secure** - use SSL
- *  * **ignoreTLS** - ignore server support for STARTTLS
- *  * **requireTLS** - forces the client to use STARTTLS
+ *  * **ignoreTLS** - ignore server support for STARTTLS (has no effect when requireTLS is set)
+ *  * **requireTLS** - forces the client to use STARTTLS, takes precedence over ignoreTLS and opportunisticTLS
  *  * **name** - the name of the client server
  *  * **localAddress** - outbound address to bind to (see: http://nodejs.org/api/net.html#net_net_connect_options_connectionlistener)
  *  * **greetingTimeout** - Time to wait in ms until greeting message is received from the server (defaults to 30 seconds)
@@ -130,6 +130,11 @@ class SMTPConnection extends node_events_1.EventEmitter {
         this.id = node_crypto_1.default.randomBytes(8).toString('base64').replace(/\W/g, '');
         this.stage = 'init';
         this.options = options || {};
+        if (this.options.requireTLS && (this.options.ignoreTLS || this.options.opportunisticTLS)) {
+            // requireTLS wins, a contradictory configuration must not quietly fall back to plaintext.
+            // Copied so the caller's (possibly shared) options object is left as it was
+            this.options = Object.assign({}, this.options, { ignoreTLS: false, opportunisticTLS: false });
+        }
         this.secureConnection = !!this.options.secure;
         this.alreadySecured = !!this.options.secured;
         this.port = Number(this.options.port) || (this.secureConnection ? 465 : 587);
@@ -173,6 +178,8 @@ class SMTPConnection extends node_events_1.EventEmitter {
         this._destroyed = false;
         this._closing = false;
         this._currentDataStream = false;
+        this._pendingSend = false;
+        this._connectCallback = false;
         this._onSocketData = chunk => this._onData(chunk);
         this._onSocketError = error => this._onError(error, 'ESOCKET', false, 'CONN');
         this._onSocketClose = () => this._onClose();
@@ -187,7 +194,9 @@ class SMTPConnection extends node_events_1.EventEmitter {
      */
     connect(connectCallback) {
         if (typeof connectCallback === 'function') {
+            this._connectCallback = connectCallback;
             this.once('connect', () => {
+                this._connectCallback = false;
                 this.logger.debug({
                     tnx: 'smtp'
                 }, 'SMTP handshake finished');
@@ -419,6 +428,16 @@ class SMTPConnection extends node_events_1.EventEmitter {
             }
             this._currentDataStream = false;
         }
+        // Detach from the message stream as well. The listener is swapped for a no-op rather than
+        // removed, a stream destroyed with an error later on would otherwise throw it as unhandled
+        if (this._pendingSend) {
+            const { stream, onStreamError } = this._pendingSend;
+            if (stream) {
+                stream.removeListener('error', onStreamError);
+                stream.on('error', TEARDOWN_NOOP);
+            }
+            this._pendingSend = false;
+        }
         if (socket && !socket.destroyed) {
             try {
                 // Clear socket timeout to prevent timer leaks
@@ -606,6 +625,9 @@ class SMTPConnection extends node_events_1.EventEmitter {
                 return;
             }
             returned = true;
+            if (this._pendingSend && this._pendingSend.callback === callback) {
+                this._pendingSend = false;
+            }
             done(err, info);
         };
         if (!message) {
@@ -622,9 +644,16 @@ class SMTPConnection extends node_events_1.EventEmitter {
             });
             return;
         }
+        const pendingSend = {
+            callback,
+            stream: false,
+            onStreamError: err => callback(this._formatError(err, 'ESTREAM', false, 'API'))
+        };
         if (typeof message.on === 'function') {
-            message.on('error', err => callback(this._formatError(err, 'ESTREAM', false, 'API')));
+            pendingSend.stream = message;
+            pendingSend.stream.on('error', pendingSend.onStreamError);
         }
+        this._pendingSend = pendingSend;
         const startTime = Date.now();
         this._setEnvelope(envelope, (err, info) => {
             if (err) {
@@ -817,8 +846,14 @@ class SMTPConnection extends node_events_1.EventEmitter {
         else {
             this.logger.error(data, err.message);
         }
+        // close() forgets the send in flight, it is completed with this same error afterwards so
+        // a late message stream error has nothing left to report
+        const pendingSend = this._pendingSend;
         this.emit('error', err);
         this.close();
+        if (pendingSend) {
+            pendingSend.callback(err);
+        }
     }
     /** @internal */
     _formatError(message, type, response, command) {
@@ -864,14 +899,25 @@ class SMTPConnection extends node_events_1.EventEmitter {
         this.logger.info({
             tnx: 'network'
         }, 'Connection closed');
+        // the unterminated remainder is only reported as a reply (and so gives the error a responseCode)
+        // when it starts like a complete failure reply, not for a fragment such as "55" or a 250
+        const failureResponse = typeof serverResponse === 'string' && /^[45]\d{2}[ -]/.test(serverResponse) ? serverResponse : false;
         if (this.upgrading && !this._destroyed) {
-            return this._onError(new Error('Connection closed unexpectedly'), 'ETLS', serverResponse, 'CONN');
-        }
-        else if (![this._actionGreeting, this.close].includes(this._responseActions[0]) && !this._destroyed) {
-            return this._onError(new Error('Connection closed unexpectedly'), 'ECONNECTION', serverResponse, 'CONN');
+            return this._onError(new Error('Connection closed unexpectedly'), 'ETLS', failureResponse, 'CONN');
+        }
+        if (!failureResponse && this._responseActions[0] === this._actionGreeting && this._connectCallback && !this._destroyed) {
+            // A silent close before the greeting is handed to the connect() callback rather than
+            // emitted as 'error', callers that never saw an error for it must not start throwing one
+            const connectCallback = this._connectCallback;
+            this._connectCallback = false;
+            const err = this._formatError(new Error('Connection closed unexpectedly'), 'ECONNECTION', false, 'CONN');
+            this.logger.warn({ tnx: 'network' }, err.message);
+            connectCallback(err);
+            this.close();
+            return;
         }
-        else if (/^[45]\d{2}\b/.test(serverResponse)) {
-            return this._onError(new Error('Connection closed unexpectedly'), 'ECONNECTION', serverResponse, 'CONN');
+        if (failureResponse || (this._responseActions[0] !== this.close && !this._destroyed)) {
+            return this._onError(new Error('Connection closed unexpectedly'), 'ECONNECTION', failureResponse, 'CONN');
         }
         this._destroy();
     }
@@ -1348,21 +1394,25 @@ class SMTPConnection extends node_events_1.EventEmitter {
         if (/[ -]AUTH\b/i.test(str)) {
             this.allowsAuth = true;
         }
-        // Detect if the server supports PLAIN auth
-        if (/[ -]AUTH(?:(\s+|=)[^\n]*\s+|\s+|=)PLAIN/i.test(str)) {
-            this._supportedAuth.push('PLAIN');
-        }
-        // Detect if the server supports LOGIN auth
-        if (/[ -]AUTH(?:(\s+|=)[^\n]*\s+|\s+|=)LOGIN/i.test(str)) {
-            this._supportedAuth.push('LOGIN');
-        }
-        // Detect if the server supports CRAM-MD5 auth
-        if (/[ -]AUTH(?:(\s+|=)[^\n]*\s+|\s+|=)CRAM-MD5/i.test(str)) {
-            this._supportedAuth.push('CRAM-MD5');
+        // Detect the advertised SASL mechanisms. The list is split into whole tokens rather
+        // than searched for each name with a pattern: the patterns this replaced let two
+        // whitespace runs overlap and backtracked quadratically over an AUTH line padded with
+        // spaces, so a hostile server could stall the event loop from its EHLO reply
+        // (GHSA-4ffr-jq9g-5ffx).
+        const authMechanisms = new Set();
+        for (const line of this._ehloLines) {
+            const authMatch = /^AUTH[\s=](.*)/i.exec(line);
+            if (authMatch) {
+                for (const mechanism of authMatch[1].split(/[\s=]+/)) {
+                    authMechanisms.add(mechanism.toUpperCase());
+                }
+            }
         }
-        // Detect if the server supports XOAUTH2 auth
-        if (/[ -]AUTH(?:(\s+|=)[^\n]*\s+|\s+|=)XOAUTH2/i.test(str)) {
-            this._supportedAuth.push('XOAUTH2');
+        // listed in order of preference, the first one the credentials allow is used
+        for (const mechanism of ['PLAIN', 'LOGIN', 'CRAM-MD5', 'XOAUTH2']) {
+            if (authMechanisms.has(mechanism)) {
+                this._supportedAuth.push(mechanism);
+            }
         }
         // Detect if the server supports SIZE extensions (and the max allowed size)
         if ((match = str.match(/[ -]SIZE(?:[ \t]+(\d+))?/im))) {
@@ -1622,7 +1672,11 @@ class SMTPConnection extends node_events_1.EventEmitter {
                 this._sendCommand('DATA');
             }
             else {
-                err = this._formatError("Can't send mail - all recipients were rejected", 'EENVELOPE', str, 'RCPT TO');
+                // report a temporary rejection when there is one, taking the last reply would mark the
+                // whole message as permanently failed although some recipients were only deferred
+                const deferred = envelope.rejectedErrors.find(rejectedErr => rejectedErr.responseCode && rejectedErr.responseCode < 500);
+                const reply = deferred?.response ?? str;
+                err = this._formatError("Can't send mail - all recipients were rejected", 'EENVELOPE', reply, 'RCPT TO');
                 err.rejected = envelope.rejected;
                 err.rejectedErrors = envelope.rejectedErrors;
                 return callback(err);

package/dist/cjs/smtp-pool/index.d.ts

@@ -17,7 +17,7 @@ export interface SMTPPoolOptions extends SMTPTransportOptions {
     rateLimit?: number | undefined;
     /** Time window for rateLimit in milliseconds, defaults to 1000 */
     rateDelta?: number | undefined;
-    /** How many times a message is requeued when its connection closes while sending, unlimited when not set or negative */
+    /** How many times a message is requeued when its connection closes while sending, defaults to 5, a negative value means unlimited */
     maxRequeues?: number | undefined;
 }
 /**
@@ -26,6 +26,7 @@ export interface SMTPPoolOptions extends SMTPTransportOptions {
 export type SMTPPoolResolvedOptions = SMTPPoolOptions & {
     maxConnections: number;
     maxMessages: number;
+    maxRequeues: number;
 };
 /**
  * Result of a message sent through the pool, same as for the SMTP transport

package/dist/cjs/smtp-pool/index.js

@@ -43,6 +43,10 @@ const index_js_2 = __importDefault(require("../well-known/index.js"));
 const shared = __importStar(require("../shared/index.js"));
 const errors = __importStar(require("../errors.js"));
 const packageData = __importStar(require("../package-info.js"));
+/** First delay before a requeued message is retried, doubled on every further requeue */
+const REQUEUE_BASE_DELAY = 50;
+/** Upper bound for the requeue delay */
+const REQUEUE_MAX_DELAY = 2000;
 /**
  * Creates a SMTP pool transport object for Nodemailer
  *
@@ -74,6 +78,8 @@ class SMTPPool extends node_events_1.EventEmitter {
         );
         this.options.maxConnections = this.options.maxConnections || 5;
         this.options.maxMessages = this.options.maxMessages || 100;
+        // a default bound, a server that closes every connection before the greeting would otherwise be retried forever
+        this.options.maxRequeues = typeof this.options.maxRequeues === 'number' ? this.options.maxRequeues : 5;
         this.logger = shared.getLogger(this.options, {
             component: this.options.component || 'smtp-pool'
         });
@@ -117,6 +123,10 @@ class SMTPPool extends node_events_1.EventEmitter {
      */
     send(mail, callback) {
         if (this._closed) {
+            // Mail.sendMail ignores the return value, so without a callback its promise would never settle
+            const err = new Error('Connection pool was closed');
+            err.code = errors.ECONNECTION;
+            setImmediate(() => callback(err));
             return false;
         }
         this._queue.push({
@@ -330,15 +340,22 @@ class SMTPPool extends node_events_1.EventEmitter {
                 // Note that we must wait a bit.. because the callback of the 'error' handler might be called
                 // in the next event loop
                 setTimeout(() => {
+                    let delay = 0;
                     if (connection.queueEntry) {
                         if (this._shouldRequeuOnConnectionClose(connection.queueEntry)) {
-                            this._requeueEntryOnConnectionClose(connection);
+                            delay = this._requeueEntryOnConnectionClose(connection);
                         }
                         else {
                             this._failDeliveryOnConnectionClose(connection);
                         }
                     }
-                    this._continueProcessing();
+                    if (delay) {
+                        // back off, a server that keeps dropping connections is not hammered
+                        setTimeout(() => this._continueProcessing(), delay);
+                    }
+                    else {
+                        this._continueProcessing();
+                    }
                 }, 50);
             }
             else {
@@ -353,7 +370,7 @@ class SMTPPool extends node_events_1.EventEmitter {
     }
     /** @internal */
     _shouldRequeuOnConnectionClose(queueEntry) {
-        if (this.options.maxRequeues === undefined || this.options.maxRequeues < 0) {
+        if (this.options.maxRequeues < 0) {
             return true;
         }
         return queueEntry.requeueAttempts < this.options.maxRequeues;
@@ -362,7 +379,9 @@ class SMTPPool extends node_events_1.EventEmitter {
     _failDeliveryOnConnectionClose(connection) {
         if (connection.queueEntry && connection.queueEntry.callback) {
             try {
-                connection.queueEntry.callback(new Error('Reached maximum number of retries after connection was closed'));
+                const err = new Error('Reached maximum number of retries after connection was closed');
+                err.code = errors.ECONNECTION;
+                connection.queueEntry.callback(err);
             }
             catch (E) {
                 this.logger.error({
@@ -377,6 +396,7 @@ class SMTPPool extends node_events_1.EventEmitter {
     }
     /** @internal */
     _requeueEntryOnConnectionClose(connection) {
+        const delay = Math.min(REQUEUE_BASE_DELAY * 2 ** connection.queueEntry.requeueAttempts, REQUEUE_MAX_DELAY);
         connection.queueEntry.requeueAttempts += 1;
         this.logger.debug({
             tnx: 'pool',
@@ -386,6 +406,7 @@ class SMTPPool extends node_events_1.EventEmitter {
         }, 'Re-queued message <%s> for #%s. Attempt: #%s', connection.queueEntry.messageId, connection.id, connection.queueEntry.requeueAttempts);
         this._queue.unshift(connection.queueEntry);
         connection.queueEntry = false;
+        return delay;
     }
     /**
      * Continue to process message if the pool hasn't closed
@@ -506,10 +527,15 @@ class SMTPPool extends node_events_1.EventEmitter {
                 connection.quit();
                 return done(null, true);
             };
-            connection.connect(() => {
+            connection.connect(err => {
                 if (returned) {
                     return;
                 }
+                if (err) {
+                    returned = true;
+                    connection.close();
+                    return done(err);
+                }
                 if (auth && (connection.allowsAuth || options.forceAuth)) {
                     connection.login(auth, err => {
                         if (returned) {

package/dist/cjs/smtp-pool/pool-resource.js

@@ -66,7 +66,7 @@ class PoolResource extends node_events_1.EventEmitter {
                         method: 'XOAUTH2'
                     };
                     oauth2.on('token', (token) => this.pool.mailer.emit('token', token));
-                    oauth2.on('error', err => this.emit('error', err));
+                    oauth2.on('error', err => this._fail(err));
                     break;
                 }
                 default:
@@ -89,6 +89,19 @@ class PoolResource extends node_events_1.EventEmitter {
         this._connected = false;
         this.messages = 0;
         this.available = true;
+        this._failed = false;
+    }
+    /**
+     * Emits 'error' for the first failure only. A dead resource can report the same failure more
+     * than once (the connection error, then the send callback), the pool handles it once
+     * @internal
+     */
+    _fail(err) {
+        if (this._failed) {
+            return;
+        }
+        this._failed = true;
+        this.emit('error', err);
     }
     /**
      * Initiates a connection to the SMTP server
@@ -101,7 +114,7 @@ class PoolResource extends node_events_1.EventEmitter {
                 // nothing was connected, so no 'close' event is coming that would free the
                 // slot this resource holds in the pool, report the failure the way a failed
                 // login does
-                this.emit('error', err);
+                this._fail(err);
                 return callback(err);
             }
             let returned = false;
@@ -118,8 +131,8 @@ class PoolResource extends node_events_1.EventEmitter {
                 options = Object.assign((0, index_js_2.assign)(false, options), socketOptions);
             }
             this.connection = new index_js_1.default(options);
-            this.connection.once('error', err => {
-                this.emit('error', err);
+            this.connection.on('error', err => {
+                this._fail(err);
                 if (returned) {
                     return;
                 }
@@ -128,33 +141,18 @@ class PoolResource extends node_events_1.EventEmitter {
             });
             this.connection.once('end', () => {
                 this.close();
-                if (returned) {
-                    return;
-                }
                 returned = true;
-                const timer = setTimeout(() => {
-                    if (returned) {
-                        return;
-                    }
-                    // still have not returned, this means we have an unexpected connection close
-                    const err = new Error('Unexpected socket close');
-                    if (this.connection && this.connection.upgrading) {
-                        // starttls connection errors
-                        err.code = errors.ETLS;
-                    }
-                    callback(err);
-                }, 1000);
-                try {
-                    timer.unref();
-                }
-                catch (_E) {
-                    // Ignore. Happens on envs with non-node timer implementation
-                }
             });
-            this.connection.connect(() => {
+            this.connection.connect(err => {
                 if (returned) {
                     return;
                 }
+                if (err) {
+                    // a close before the greeting, the 'end' that follows closes this resource
+                    // and the pool requeues or fails the entry, bounded by maxRequeues
+                    returned = true;
+                    return;
+                }
                 if (this.auth && (this.connection.allowsAuth || options.forceAuth)) {
                     this.connection.login(this.auth, err => {
                         if (returned) {
@@ -163,7 +161,7 @@ class PoolResource extends node_events_1.EventEmitter {
                         returned = true;
                         if (err) {
                             this.connection.close();
-                            this.emit('error', err);
+                            this._fail(err);
                             return callback(err);
                         }
                         this._connected = true;
@@ -215,7 +213,7 @@ class PoolResource extends node_events_1.EventEmitter {
             this.messages++;
             if (err) {
                 this.connection.close();
-                this.emit('error', err);
+                this._fail(err);
                 return callback(err);
             }
             info.envelope = {
@@ -228,7 +226,7 @@ class PoolResource extends node_events_1.EventEmitter {
                     const err = new Error('Resource exhausted');
                     err.code = errors.EMAXLIMIT;
                     this.connection.close();
-                    this.emit('error', err);
+                    this._fail(err);
                 }
                 else {
                     this.pool._checkRateLimit(() => {

package/dist/cjs/smtp-transport/index.js

@@ -177,31 +177,6 @@ class SMTPTransport extends node_events_1.EventEmitter {
                 connection.close();
                 return callback(err);
             });
-            connection.once('end', () => {
-                if (returned) {
-                    return;
-                }
-                const timer = setTimeout(() => {
-                    if (returned) {
-                        return;
-                    }
-                    returned = true;
-                    cleanupPerCallAuth();
-                    // still have not returned, this means we have an unexpected connection close
-                    const err = new Error('Unexpected socket close');
-                    if (connection && connection.upgrading) {
-                        // starttls connection errors
-                        err.code = errors.ETLS;
-                    }
-                    callback(err);
-                }, 1000);
-                try {
-                    timer.unref();
-                }
-                catch (_E) {
-                    // Ignore. Happens on envs with non-node timer implementation
-                }
-            });
             const sendMessage = () => {
                 const envelope = mail.message.getEnvelope();
                 const messageId = mail.message.messageId();
@@ -221,6 +196,10 @@ class SMTPTransport extends node_events_1.EventEmitter {
                     messageId
                 }, 'Sending message %s to <%s>', messageId, recipients.join(', '));
                 connection.send(envelope, mail.message.createReadStream(), (err, info) => {
+                    if (returned) {
+                        // the connection error handler has already reported this send
+                        return;
+                    }
                     returned = true;
                     cleanupPerCallAuth();
                     connection.close();
@@ -247,10 +226,16 @@ class SMTPTransport extends node_events_1.EventEmitter {
                     }
                 });
             };
-            connection.connect(() => {
+            connection.connect(err => {
                 if (returned) {
                     return;
                 }
+                if (err) {
+                    // the server closed the connection before the greeting
+                    returned = true;
+                    connection.close();
+                    return callback(err);
+                }
                 perCallAuth = this.getAuth(mail.data.auth);
                 if (perCallAuth && (connection.allowsAuth || options.forceAuth)) {
                     connection.login(perCallAuth, err => {
@@ -332,10 +317,15 @@ class SMTPTransport extends node_events_1.EventEmitter {
                 connection.quit();
                 return done(null, true);
             };
-            connection.connect(() => {
+            connection.connect(err => {
                 if (returned) {
                     return;
                 }
+                if (err) {
+                    returned = true;
+                    connection.close();
+                    return done(err);
+                }
                 perCallAuth = this.getAuth({});
                 if (perCallAuth && (connection.allowsAuth || options.forceAuth)) {
                     connection.login(perCallAuth, err => {

package/dist/cjs/xoauth2/index.d.ts

@@ -61,6 +61,8 @@ export interface XOAuth2Options {
     component?: string | undefined;
     /** Extra headers for the token request */
     customHeaders?: OutgoingHttpHeaders | undefined;
+    /** Timeout for the token request in milliseconds, defaults to 60000, 0 disables it */
+    requestTimeout?: number | undefined;
     /** Extra form fields for the token request */
     customParams?: {
         [key: string]: any;

package/dist/cjs/xoauth2/index.js

@@ -74,12 +74,14 @@ class XOAuth2 extends node_stream_1.Stream {
     constructor(options, logger) {
         super();
         this.options = options || {};
+        this.configError = false;
         if (options && options.serviceClient) {
             if (!options.privateKey || !options.user) {
+                // reported through getToken() rather than an 'error' event: the transports forward
+                // that event up to the Mail object, where nothing may be listening
                 const err = new Error('Options "privateKey" and "user" are required for service account!');
                 err.code = errors.EOAUTH2;
-                setImmediate(() => this.emit('error', err));
-                return;
+                this.configError = err;
             }
             const serviceRequestTimeout = Math.min(Math.max(Number(this.options.serviceRequestTimeout) || 0, 0), 3600);
             this.options.serviceRequestTimeout = serviceRequestTimeout || 5 * 60;
@@ -113,6 +115,9 @@ class XOAuth2 extends node_stream_1.Stream {
     getToken(renew, callback) {
         // the error paths hand over the error alone
         const done = callback;
+        if (this.configError) {
+            return done(this.configError);
+        }
         if (!renew && this.accessToken && (!this.expires || this.expires > Date.now())) {
             this.logger.debug({
                 tnx: 'OAUTH2',
@@ -349,7 +354,10 @@ class XOAuth2 extends node_stream_1.Stream {
             method: 'post',
             headers: params.customHeaders,
             body: payload,
-            allowErrorResponse: true
+            allowErrorResponse: true,
+            // unset falls back to the fetch default, a stalled token endpoint would otherwise keep
+            // `renewing` set and queue every later request
+            timeout: params.requestTimeout
         };
         // OAuth2 token endpoints are credential-bearing. src/fetch already
         // validates certs by default; pin rejectUnauthorized:true here so the

package/dist/esm/addressparser/index.js

@@ -240,6 +240,81 @@ function _recoverAddrSpec(data) {
         .filter(part => part)
         .join(' ');
 }
+/**
+ * Takes the RFC 5322 comments out of the contents of an angle-addr.
+ *
+ * The tokenizer tracks a single open operator, so once '<' is open a '(' is plain text and
+ * a comment inside the brackets reached the address verbatim: 'Name <user@example.com(x)evil.com>'
+ * put 'user@example.com(x)evil.com' into the envelope, a value that is no mailbox and that a
+ * receiver stripping the comment reads as 'user@example.comevil.com' (GHSA-g73g-hqqh-jr95).
+ * A comment is folding whitespace, so it is read as a space that splits two atoms and as
+ * nothing next to an '@', the same rule the token walk applies outside the brackets. Quoted
+ * strings and domain literals are copied through untouched, a '(' in there is not a comment.
+ *
+ * @param address Contents of the angle brackets
+ * @return The address with the comments removed, and the text of the comments
+ */
+function _stripAddressComments(address) {
+    const comments = [];
+    let result = '';
+    let comment = '';
+    let depth = 0;
+    let closer = '';
+    // carried along rather than read back off the growing result, which would flatten it on
+    // every comment (see lastChars in _handleAddress)
+    let lastChar = '';
+    for (let i = 0, len = address.length; i < len; i++) {
+        const chr = address.charAt(i);
+        if (depth) {
+            if (chr === '\\' && i < len - 1) {
+                comment += address.charAt(++i);
+            }
+            else if (chr === '(') {
+                depth++;
+                comment += chr;
+            }
+            else if (chr === ')' && !--depth) {
+                comments.push(comment.trim());
+                comment = '';
+                if (lastChar !== '@' && address.charAt(i + 1) !== '@') {
+                    result += ' ';
+                    lastChar = ' ';
+                }
+            }
+            else {
+                comment += chr;
+            }
+            continue;
+        }
+        if (closer) {
+            if (chr === '\\' && closer === '"' && i < len - 1) {
+                result += chr + address.charAt(++i);
+                lastChar = address.charAt(i);
+                continue;
+            }
+            if (chr === closer) {
+                closer = '';
+            }
+        }
+        else if (chr === '"') {
+            closer = '"';
+        }
+        else if (chr === '[') {
+            closer = ']';
+        }
+        else if (chr === '(') {
+            depth = 1;
+            continue;
+        }
+        result += chr;
+        lastChar = chr;
+    }
+    if (depth) {
+        // an unterminated comment runs to the end of the address
+        comments.push(comment.trim());
+    }
+    return { address: result.trim(), comments: comments.filter(text => text) };
+}
 /**
  * Converts tokens for a single address into an address object
  *
@@ -367,6 +442,24 @@ function _handleAddress(tokens, depth) {
         });
     }
     else {
+        // Comments come out of the angle-addr before anything asks whether one was found, so
+        // that brackets holding nothing but a comment read the same as empty ones
+        const addressComments = [];
+        const addressParts = [];
+        for (const part of data.address) {
+            if (part.indexOf('(') < 0) {
+                addressParts.push(part);
+                continue;
+            }
+            const stripped = _stripAddressComments(part);
+            for (const comment of stripped.comments) {
+                addressComments.push(comment);
+            }
+            if (stripped.address) {
+                addressParts.push(stripped.address);
+            }
+        }
+        data.address = addressParts;
         // If no address was found, try to detect one from regular text
         if (!data.address.length && data.text.length) {
             for (let i = data.text.length - 1; i >= 0; i--) {
@@ -433,6 +526,10 @@ function _handleAddress(tokens, depth) {
             data.text = '';
         }
         _recoverAddrSpec(data);
+        // a comment names the mailbox only when nothing else does, as one outside the brackets
+        if (!data.text && addressComments.length) {
+            data.text = addressComments.join(' ');
+        }
         const address = {
             address: data.address || data.text || '',
             name: data.text || data.address || ''