Add support for SUBSCRIBE, UNSUBSCRIBE and LSUB

IMAP can subscribe to / unsubscribe from folders. Servers such as
Dovecot do not automatically subscribe to newly created mailboxes, you
must subscribe to them after creation.

subscribeBox - Subscribes to the specified box.
unsubcribeBox - Unsubscribes from the specified box.
getSubscribedBoxes - Issues a LSUB command to the server. Whilst LIST
returns all folders, LSUB only returns the folders the user has
subscribed to.

README.md

@@ -408,6 +408,10 @@ Connection Instance Methods
 
 * **renameBox**(< _string_ >oldMailboxName, < _string_ >newMailboxName, < _function_ >callback) - _(void)_ - Renames a specific mailbox that exists on the server. Both `oldMailboxName` and `newMailboxName` should include any necessary prefix/path. `callback` has 2 parameters: < _Error_ >err, < _Box_ >mailbox. **Note:** Renaming the 'INBOX' mailbox will instead cause all messages in 'INBOX' to be moved to the new mailbox.
 
+* **subscribeBox**(< _string_ >mailboxName, < _function_ >callback) - _(void)_ - Subscribes to a specific mailbox that exists on the server. `mailboxName` should include any necessary prefix/path. `callback` has 1 parameter: < _Error_ >err.
+
+* **unsubscribeBox**(< _string_ >mailboxName, < _function_ >callback) - _(void)_ - Unsubscribes from a specific mailbox that exists on the server. `mailboxName` should include any necessary prefix/path. `callback` has 1 parameter: < _Error_ >err.
+
 * **status**(< _string_ >mailboxName, < _function_ >callback) - _(void)_ - Fetches information about a mailbox other than the one currently open. `callback` has 2 parameters: < _Error_ >err, < _Box_ >mailbox. **Note:** There is no guarantee that this will be a fast operation on the server. Also, do **not** call this on the currently open mailbox.
 
 * **getBoxes**([< _string_ >nsPrefix,] < _function_ >callback) - _(void)_ - Obtains the full list of mailboxes. If `nsPrefix` is not specified, the main personal namespace is used. `callback` has 2 parameters: < _Error_ >err, < _object_ >boxes. `boxes` has the following format (with example values):
@@ -479,6 +483,8 @@ Connection Instance Methods
     }
     ```
 
+* **getSubscribedBoxes**([< _string_ >nsPrefix,] < _function_ >callback) - _(void)_ - Obtains the full list of subscribed mailboxes. If `nsPrefix` is not specified, the main personal namespace is used. `callback` has 2 parameters: < _Error_ >err, < _object_ >boxes. `boxes` has the same format as getBoxes above.
+
 * **expunge**(< _function_ >callback) - _(void)_ - Permanently removes all messages flagged as Deleted in the currently open mailbox. `callback` has 1 parameter: < _Error_ >err. **Note:** At least on Gmail, performing this operation with any currently open mailbox that is not the Spam or Trash mailbox will merely archive any messages marked as Deleted (by moving them to the 'All Mail' mailbox).
 
 * **append**(< _mixed_ >msgData, [< _object_ >options,] < _function_ >callback) - _(void)_ - Appends a message to selected mailbox. `msgData` is a string or Buffer containing an RFC-822 compatible MIME message. Valid `options` properties are:

lib/Connection.js

@@ -381,6 +381,25 @@ Connection.prototype.renameBox = function(oldname, newname, cb) {
   );
 };
 
+Connection.prototype.subscribeBox = function(name, cb) {
+	this._enqueue('SUBSCRIBE "' + escape(utf7.encode(''+name)) + '"', cb);
+};
+
+Connection.prototype.unsubscribeBox = function(name, cb) {
+	this._enqueue('UNSUBSCRIBE "' + escape(utf7.encode(''+name)) + '"', cb);
+};
+
+Connection.prototype.getSubscribedBoxes = function(namespace, cb) {
+	if (typeof namespace === 'function') {
+		cb = namespace;
+		namespace = '';
+	}
+
+	namespace = escape(utf7.encode(''+namespace));
+
+	this._enqueue('LSUB "' + namespace + '" "*"', cb);
+};
+
 Connection.prototype.status = function(boxName, cb) {
   if (this._box && this._box.name === boxName)
     throw new Error('Cannot call status on currently selected mailbox');
@@ -1130,7 +1149,7 @@ Connection.prototype._resUntagged = function(info) {
     } else if (typeof info.textCode === 'string'
                && info.textCode.toUpperCase() === 'UIDVALIDITY')
       this.emit('uidvalidity', info.text);
-  } else if (type === 'list') {
+  } else if (type === 'list' || type === 'lsub') {
     if (this.delimiter === undefined)
       this.delimiter = info.text.delimiter;
     else {