You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

35 KiB

Raw Blame History

Description

node-imap is an IMAP client module for node.js.

This module does not perform any magic such as auto-decoding of messages/attachments or parsing of email addresses (node-imap leaves all mail header values as-is).

Requirements

node.js -- v0.8.0 or newer
- NOTE: node v0.8.x users are supported via the readable-stream module which may not be up-to-date (compared to node v0.10 streams2 implementation)
An IMAP server -- tested with gmail

Installation

npm install imap

Examples

Fetch the 'date', 'from', 'to', 'subject' message headers and the message structure of the first 3 messages in the Inbox:

var Imap = require('imap'),
    inspect = require('util').inspect;

var imap = new Imap({
  user: 'mygmailname@gmail.com',
  password: 'mygmailpassword',
  host: 'imap.gmail.com',
  port: 993,
  secure: true,
  secureOptions: { rejectUnauthorized: false }
});

function openInbox(cb) {
  imap.openBox('INBOX', true, cb);
}

imap.once('ready', function() {
  openInbox(function(err, box) {
    if (err) throw err;
    var f = imap.fetch('1:3', {
      bodies: 'HEADER.FIELDS (FROM TO SUBJECT DATE)',
      struct: true
    });
    f.on('message', function(msg, seqno) {
      console.log('Message #%d', seqno);
      var prefix = '(#' + seqno + ') ';
      msg.on('body', function(stream, info) {
        var buffer = '';
        stream.on('data', function(chunk) {
          buffer += chunk.toString('utf8');
        });
        stream.once('end', function() {
          console.log(prefix + 'Parsed header: %s', inspect(Imap.parseHeader(buffer)));
        });
      });
      msg.once('attributes', function(attrs) {
        console.log(prefix + 'Attributes: %s', inspect(attrs, false, 8));
      });
      msg.once('end', function() {
        console.log(prefix + 'Finished');
      });
    });
    f.once('error', function(err) {
      console.log('Fetch error: ' + err);
    });
    f.once('end', function() {
      console.log('Done fetching all messages!');
      imap.end();
    });
  });
});

imap.once('error', function(err) {
  console.log(err);
});

imap.once('end', function() {
  console.log('Connection ended');
});

imap.connect();

Retrieve the 'from' header and buffer the entire body of the newest message:

// using the functions and variables already defined in the first example ...

openInbox(function(err, box) {
  if (err) throw err;
  var f = imap.seq.fetch(box.messages.total + ':*', { bodies: ['HEADER.FIELDS (FROM)','TEXT'] });
  f.on('message', function(msg, seqno) {
    console.log('Message #%d', seqno);
    var prefix = '(#' + seqno + ') ';
    msg.on('body', function(stream, info) {
      if (info.which === 'TEXT')
        console.log(prefix + 'Body [%s] found, %d total bytes', inspect(info.which), info.size);
      var buffer = '', count = 0;
      stream.on('data', function(chunk) {
        count += chunk.length;
        buffer += chunk.toString('utf8');
        if (info.which === 'TEXT')
          console.log(prefix + 'Body [%s] (%d/%d)', inspect(info.which), count, info.size);
      });
      stream.once('end', function() {
        if (info.which !== 'TEXT')
          console.log(prefix + 'Parsed header: %s', inspect(Imap.parseHeader(buffer)));
        else
          console.log(prefix + 'Body [%s] Finished', inspect(info.which));
      });
    });
    msg.once('attributes', function(attrs) {
      console.log(prefix + 'Attributes: %s', inspect(attrs, false, 8));
    });
    msg.once('end', function() {
      console.log(prefix + 'Finished');
    });
  });
  f.once('error', function(err) {
    console.log('Fetch error: ' + err);
  });
  f.once('end', function() {
    console.log('Done fetching all messages!');
    imap.end();
  });
});

Save raw unread emails since May 20, 2010 to files:

// using the functions and variables already defined in the first example ...

var fs = require('fs'), fileStream;

openInbox(function(err, box) {
  if (err) throw err;
  imap.search([ 'UNSEEN', ['SINCE', 'May 20, 2010'] ], function(err, results) {
    if (err) throw err;
    var f = imap.fetch(results, { bodies: '' });
    f.on('message', function(msg, seqno) {
      console.log('Message #%d', seqno);
      var prefix = '(#' + seqno + ') ';
      msg.on('body', function(stream, info) {
        console.log(prefix + 'Body');
        stream.pipe(fs.createWriteStream('msg-' + seqno + '-body.txt'));
      });
      msg.once('attributes', function(attrs) {
        console.log(prefix + 'Attributes: %s', inspect(attrs, false, 8));
      });
      msg.once('end', function() {
        console.log(prefix + 'Finished');
      });
    });
    f.once('error', function(err) {
      console.log('Fetch error: ' + err);
    });
    f.once('end', function() {
      console.log('Done fetching all messages!');
      imap.end();
    });
  });
});

API

Data types

Box is an object representing the currently open mailbox, and has the following properties:
- name - < string > - The name of this mailbox.
- readOnly - < boolean > - True if this mailbox was opened in read-only mode. (Only available with openBox() calls)
- uidvalidity - < integer > - A 32-bit number that can be used to determine if UIDs in this mailbox have changed since the last time this mailbox was opened.
- uidnext - < integer > - The uid that will be assigned to the next message that arrives at this mailbox.
- permFlags - < array > - A list of flags that can be permanently added/removed to/from messages in this mailbox.
- messages - < object > Contains various message counts for this mailbox:
  - total - < integer > - Total number of messages in this mailbox.
  - new - < integer > - Number of messages in this mailbox having the Recent flag (this IMAP session is the first to see these messages).
  - unseen - < integer > - (Only available with status() calls) Number of messages in this mailbox not having the Seen flag (marked as not having been read).
ImapMessage is an object representing an email message. It consists of:
- Events:
  - body(< ReadableStream >stream, < object >info) - Emitted for each requested body. Example info properties:
    - which - < string > - The specifier for this body (e.g. 'TEXT', 'HEADER.FIELDS (TO FROM SUBJECT)', etc).
    - size - < integer > - The size of this body in bytes.
  - attributes(< object >attrs) - Emitted when all message attributes have been collected. Example attrs properties:
    - uid - < integer > - A 32-bit ID that uniquely identifies this message within its mailbox.
    - flags - < array > - A list of flags currently set on this message.
    - date - < string > - The internal server date for the message (always represented in GMT?)
    - struct - < array > - The message's body structure (only set if requested with fetch()). See below for an explanation of the format of this property.
    - size - < integer > - The RFC822 message size (only set if requested with fetch()).
  - end() - Emitted when all attributes and bodies have been parsed.
ImapFetch is an object representing a fetch() request. It consists of:
- Events:
  - message(< ImapMessage >msg, < integer >seqno) - Emitted for each message resulting from a fetch request. seqno is the message's sequence number.
  - error(< Error >err) - Emitted when an error occurred.
  - end() - Emitted when all messages have been parsed.

A message structure with multiple parts might look something like the following:

[ { type: 'mixed',
    params: { boundary: '000e0cd294e80dc84c0475bf339d' },
    disposition: null,
    language: null,
    location: null
  },
  [ { type: 'alternative',
      params: { boundary: '000e0cd294e80dc83c0475bf339b' },
      disposition: null,
      language: null
    },
    [ { partID: '1.1',
        type: 'text',
        subtype: 'plain',
        params: { charset: 'ISO-8859-1' },
        id: null,
        description: null,
        encoding: '7BIT',
        size: 935,
        lines: 46,
        md5: null,
        disposition: null,
        language: null
      }
    ],
    [ { partID: '1.2',
        type: 'text',
        subtype: 'html',
        params: { charset: 'ISO-8859-1' },
        id: null,
        description: null,
        encoding: 'QUOTED-PRINTABLE',
        size: 1962,
        lines: 33,
        md5: null,
        disposition: null,
        language: null
      }
    ]
  ],
  [ { partID: '2',
      type: 'application',
      subtype: 'octet-stream',
      params: { name: 'somefile' },
      id: null,
      description: null,
      encoding: 'BASE64',
      size: 98,
      lines: null,
      md5: null,
      disposition:
       { type: 'attachment',
         params: { filename: 'somefile' }
       },
      language: null,
      location: null
    }
  ]
]

The above structure describes a message having both an attachment and two forms of the message body (plain text and HTML). Each message part is identified by a partID which is used when you want to fetch the content of that part (see fetch()).

The structure of a message with only one part will simply look something like this:

[ { partID: '1',
    type: 'text',
    subtype: 'plain',
    params: { charset: 'ISO-8859-1' },
    id: null,
    description: null,
    encoding: '7BIT',
    size: 935,
    lines: 46,
    md5: null,
    disposition: null,
    language: null
  }
]

Therefore, an easy way to check for a multipart message is to check if the structure length is >1.

Lastly, here are the system flags defined by RFC3501 that may be added/removed:

Seen - Message has been read
Answered - Message has been answered
Flagged - Message is "flagged" for urgent/special attention
Deleted - Message is "deleted" for removal
Draft - Message has not completed composition (marked as a draft).

It should be noted however that the IMAP server can limit which flags can be permanently modified for any given message. If in doubt, check the mailbox's permFlags first. Additional custom flags may be provided by the server. If available, these will also be listed in the mailbox's permFlags.

require('imap') returns one object: Connection.

Connection Events

ready() - Emitted when a connection to the server has been made and authentication was successful.
alert(< string >message) - Emitted when the server issues an alert (e.g. "the server is going down for maintenance").
mail(< integer >numNewMsgs) - Emitted when new mail arrives in the currently open mailbox.
deleted(< integer >seqno) - Emitted when a message is deleted from another IMAP connection's session. seqno is the sequence number (instead of the unique UID) of the message that was deleted. If you are caching sequence numbers, all sequence numbers higher than this value MUST be decremented by 1 in order to stay synchronized with the server and to keep correct continuity.
error(< Error >err) - Emitted when an error occurs. The 'source' property will be set to indicate where the error originated from.
close(< boolean >hadError) - Emitted when the connection has completely closed.
end() - Emitted when the connection has ended.

Connection Properties

state - string - The current state of the connection (e.g. 'disconnected', 'connected', 'authenticated').
delimiter - string - The (top-level) mailbox hierarchy delimiter. If the server does not support mailbox hierarchies and only a flat list, this value will be falsey.

namespaces - object - Contains information about each namespace type (if supported by the server) with the following properties:

personal - array - Mailboxes that belong to the logged in user.
other - array - Mailboxes that belong to other users that the logged in user has access to.
shared - array - Mailboxes that are accessible by any logged in user.

There should always be at least one entry (although the IMAP spec allows for more, it doesn't seem to be very common) in the personal namespace list, with a blank namespace prefix. Each property's array contains objects of the following format (with example values):

{ prefix: '', // A string containing the prefix to use to access mailboxes in this namespace
  delimiter: '/', // A string containing the hierarchy delimiter for this namespace, or boolean false
                  //  for a flat namespace with no hierarchy
  extensions: [ // An array of namespace extensions supported by this namespace, or null if none
                // are specified
    { name: 'X-FOO-BAR', // A string indicating the extension name
      params: [ 'BAZ' ] // An array of strings containing the parameters for this extension,
                        // or null if none are specified
    }
  ]
}

Connection Static Methods

parseHeader(< string >rawHeader) - object - Parses a raw header and returns an object keyed on header fields and the values are Arrays of header field values.

Connection Instance Methods

Note: Message UID ranges are not guaranteed to be contiguous.

(constructor)([< object >config]) - Connection - Creates and returns a new instance of Connection using the specified configuration object. Valid config properties are:
- user - < string > - Username for plain-text authentication.
- password - < string > - Password for plain-text authentication.
- xoauth - < string > - OAuth token for OAuth authentication for servers that support it (See Andris Reinman's xoauth.js module to help generate this string).
- xoauth2 - < string > - OAuth2 token for The SASL XOAUTH2 Mechanism for servers that support it (See Andris Reinman's xoauth2 module to help generate this string).
- host - < string > - Hostname or IP address of the IMAP server. Default: "localhost"
- port - < integer > - Port number of the IMAP server. Default: 143
- secure - < boolean > - Use SSL/TLS? Default: false
- secureOptions - < object > - Options object to pass to tls.connect() Default: (none)
- connTimeout - < integer > - Number of milliseconds to wait for a connection to be established. Default: 10000
- keepalive - < boolean > - Enable the keepalive mechnanism. Default: true
- debug - < function > - If set, the function will be called with one argument, a string containing some debug info Default:
connect() - (void) - Attempts to connect and authenticate with the IMAP server.
end() - (void) - Closes the connection to the server.
openBox(< string >mailboxName[, < boolean >openReadOnly=false], < function >callback) - (void) - Opens a specific mailbox that exists on the server. mailboxName should include any necessary prefix/path. callback has 2 parameters: < Error >err, < Box >mailbox.
closeBox([< boolean >autoExpunge=true, ]< function >callback) - (void) - Closes the currently open mailbox. If autoExpunge is true, any messages marked as Deleted in the currently open mailbox will be removed if the mailbox was NOT opened in read-only mode. If autoExpunge is false, you disconnect, or you open another mailbox, messages marked as Deleted will NOT be removed from the currently open mailbox. callback has 1 parameter: < Error >err.
addBox(< string >mailboxName, < function >callback) - (void) - Creates a new mailbox on the server. mailboxName should include any necessary prefix/path. callback has 1 parameter: < Error >err.
delBox(< string >mailboxName, < function >callback) - (void) - Removes a specific mailbox that exists on the server. mailboxName should including any necessary prefix/path. callback has 1 parameter: < Error >err.
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.
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):

{ INBOX: // mailbox name
   { attribs: [], // mailbox attributes. An attribute of 'NOSELECT' indicates the mailbox cannot
                  // be opened
     delimiter: '/', // hierarchy delimiter for accessing this mailbox's direct children.
     children: null, // an object containing another structure similar in format to this top level,
                    // otherwise null if no children
     parent: null // pointer to parent mailbox, null if at the top level
   },
  Work:
   { attribs: [],
     delimiter: '/',
     children: null,
     parent: null
   },
  '[Gmail]':
   { attribs: [ 'NOSELECT' ],
     delimiter: '/',
     children:
      { 'All Mail':
         { attribs: [ 'All' ],
           delimiter: '/',
           children: null,
           parent: [Circular]
         },
        Drafts:
         { attribs: [ 'Drafts' ],
           delimiter: '/',
           children: null,
           parent: [Circular]
         },
        Important:
         { attribs: [ 'Important' ],
           delimiter: '/',
           children: null,
           parent: [Circular]
         },
        'Sent Mail':
         { attribs: [ 'Sent' ],
           delimiter: '/',
           children: null,
           parent: [Circular]
         },
        Spam:
         { attribs: [ 'Junk' ],
           delimiter: '/',
           children: null,
           parent: [Circular]
         },
        Starred:
         { attribs: [ 'Flagged' ],
           delimiter: '/',
           children: null,
           parent: [Circular]
         },
        Trash:
         { attribs: [ 'Trash' ],
           delimiter: '/',
           children: null,
           parent: [Circular]
         }
      },
     parent: null
   }
}

removeDeleted(< function >callback) - (void) - Permanently removes (EXPUNGEs) 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:
- mailbox - < string > - The name of the mailbox to append the message to. Default: the currently open mailbox
- flags - < mixed > - A single flag (e.g. 'Seen') or an array of flags (e.g. ['Seen', 'Flagged']) to append to the message. Default: (no flags)
- date - < date > - What to use for message arrival date/time. Default: (current date/time)
callback has 1 parameter: < Error >err.

All functions below have sequence number-based counterparts that can be accessed by using the 'seq' namespace of the imap connection's instance (e.g. conn.seq.search() returns sequence number(s) instead of UIDs, conn.seq.fetch() fetches by sequence number(s) instead of UIDs, etc):

search(< array >criteria, < function >callback) - (void) - Searches the currently open mailbox for messages using given criteria. criteria is a list describing what you want to find. For criteria types that require arguments, use an array instead of just the string criteria type name (e.g. ['FROM', 'foo@bar.com']). Prefix criteria types with an "!" to negate.
- The following message flags are valid types that do not have arguments:
  - 'ALL' - All messages.
  - 'ANSWERED' - Messages with the Answered flag set.
  - 'DELETED' - Messages with the Deleted flag set.
  - 'DRAFT' - Messages with the Draft flag set.
  - 'FLAGGED' - Messages with the Flagged flag set.
  - 'NEW' - Messages that have the Recent flag set but not the Seen flag.
  - 'SEEN' - Messages that have the Seen flag set.
  - 'RECENT' - Messages that have the Recent flag set.
  - 'OLD' - Messages that do not have the Recent flag set. This is functionally equivalent to "!RECENT" (as opposed to "!NEW").
  - 'UNANSWERED' - Messages that do not have the Answered flag set.
  - 'UNDELETED' - Messages that do not have the Deleted flag set.
  - 'UNDRAFT' - Messages that do not have the Draft flag set.
  - 'UNFLAGGED' - Messages that do not have the Flagged flag set.
  - 'UNSEEN' - Messages that do not have the Seen flag set.
- The following are valid types that require string value(s):
  - 'BCC' - Messages that contain the specified string in the BCC field.
  - 'CC' - Messages that contain the specified string in the CC field.
  - 'FROM' - Messages that contain the specified string in the FROM field.
  - 'SUBJECT' - Messages that contain the specified string in the SUBJECT field.
  - 'TO' - Messages that contain the specified string in the TO field.
  - 'BODY' - Messages that contain the specified string in the message body.
  - 'TEXT' - Messages that contain the specified string in the header OR the message body.
  - 'KEYWORD' - Messages with the specified keyword set.
  - 'HEADER' - Requires two string values, with the first being the header name and the second being the value to search for. If this second string is empty, all messages that contain the given header name will be returned.
- The following are valid types that require a string parseable by JavaScript's Date object OR a Date instance:
  - 'BEFORE' - Messages whose internal date (disregarding time and timezone) is earlier than the specified date.
  - 'ON' - Messages whose internal date (disregarding time and timezone) is within the specified date.
  - 'SINCE' - Messages whose internal date (disregarding time and timezone) is within or later than the specified date.
  - 'SENTBEFORE' - Messages whose Date header (disregarding time and timezone) is earlier than the specified date.
  - 'SENTON' - Messages whose Date header (disregarding time and timezone) is within the specified date.
  - 'SENTSINCE' - Messages whose Date header (disregarding time and timezone) is within or later than the specified date.
- The following are valid types that require one Integer value:
  - 'LARGER' - Messages with a size larger than the specified number of bytes.
  - 'SMALLER' - Messages with a size smaller than the specified number of bytes.
- The following are valid criterion that require one or more Integer values:
  - 'UID' - Messages with UIDs corresponding to the specified UID set. Ranges are permitted (e.g. '2504:2507' or '*' or '2504:*').
- Note 1: For the UID-based search (i.e. "conn.search()"), you can retrieve the UIDs for sequence numbers by just supplying an array of sequence numbers and/or ranges as a criteria (e.g. [ '24:29', 19, '66:*' ]).
- Note 2: By default, all criterion are ANDed together. You can use the special 'OR' on two criterion to find messages matching either search criteria (see example below).
criteria examples:
- Unread messages since April 20, 2010: [ 'UNSEEN', ['SINCE', 'April 20, 2010'] ]
- Messages that are EITHER unread OR are dated April 20, 2010 or later, you could use: [ ['OR', 'UNSEEN', ['SINCE', 'April 20, 2010'] ] ]
- All messages that have 'node-imap' in the subject header: [ ['HEADER', 'SUBJECT', 'node-imap'] ]
- All messages that do not have 'node-imap' in the subject header: [ ['!HEADER', 'SUBJECT', 'node-imap'] ]
callback has 2 parameters: < Error >err, < array >UIDs.

fetch(< mixed >source, [< object >options]) - ImapFetch - Fetches message(s) in the currently open mailbox. source can be a message UID, a message UID range (e.g. '2504:2507' or '*' or '2504:*'), or an array of message UIDs and/or message UID ranges.

Valid options properties are:

* **markSeen** - < _boolean_ > - Mark message(s) as read when fetched. **Default:** false
* **struct** - < _boolean_ > - Fetch the message structure. **Default:** false
* **size** - < _boolean_ > - Fetch the RFC822 size. **Default:** false
* **bodies** - < _mixed_ > - A string or Array of strings containing the body part section to fetch. **Default:** (none) Example sections:

    * 'HEADER' - The message header
    * 'HEADER.FIELDS(TO FROM SUBJECT)' - Specific header fields only
    * 'HEADER.FIELDS.NOT(TO FROM SUBJECT)' - Header fields only that do not match the fields given
    * 'TEXT' - The message body
    * '' - The entire message (header + body)
    * 'MIME' - MIME-related header fields only (e.g. 'Content-Type')

    **Note:** You can also prefix `bodies` strings with part ids for multipart messages (e.g. '1.TEXT', '1.2.TEXT', '2.MIME', etc)
    **Note 2:** 'HEADER*' sections are only valid for parts whose content type is 'message/rfc822', including the root part.

copy(< mixed >source, < string >mailboxName, < function >callback) - (void) - Copies message(s) in the currently open mailbox to another mailbox. source can be a message UID, a message UID range (e.g. '2504:2507' or '*' or '2504:*'), or an array of message UIDs and/or message UID ranges. callback has 1 parameter: < Error >err.
move(< mixed >source, < string >mailboxName, < function >callback) - (void) - Moves message(s) in the currently open mailbox to another mailbox. source can be a message UID, a message UID range (e.g. '2504:2507' or '*' or '2504:*'), or an array of message UIDs and/or message UID ranges. callback has 1 parameter: < Error >err. Note: The message(s) in the destination mailbox will have a new message UID.
addFlags(< mixed >source, < mixed >flags, < function >callback) - (void) - Adds flag(s) to message(s). source can be a message UID, a message UID range (e.g. '2504:2507' or '*' or '2504:*'), or an array of message UIDs and/or message UID ranges. flags is either a single flag or an array of flags. callback has 1 parameter: < Error >err.
delFlags(< mixed >source, < mixed >flags, < function >callback) - (void) - Removes flag(s) from message(s). source can be a message UID, a message UID range (e.g. '2504:2507' or '*' or '2504:*'), or an array of message UIDs and/or message UID ranges. flags is either a single flag or an array of flags. callback has 1 parameter: < Error >err.
addKeywords(< mixed >source, < mixed >keywords, < function >callback) - (void) - Adds keyword(s) to message(s). source can be a message UID, a message UID range (e.g. '2504:2507' or '*' or '2504:*'), or an array of message UIDs and/or message UID ranges. keywords is either a single keyword or an array of keywords. callback has 1 parameter: < Error >err.
delKeywords(< mixed >source, < mixed >keywords, < function >callback) - (void) - Removes keyword(s) from message(s). source can be a message UID, a message UID range (e.g. '2504:2507' or '*' or '2504:*'), or an array of message UIDs and/or message UID ranges. keywords is either a single keyword or an array of keywords. callback has 1 parameter: < Error >err.
serverSupports(< string >capability) - boolean - Checks if the server supports the specified capability.

Extensions Supported

Gmail
- Server capability: X-GM-EXT-1
- search() criteria extensions
  - X-GM-RAW: string value which allows you to use Gmail's web interface search syntax, such as: "has:attachment in:unread"
  - X-GM-THRID: allows you to search for a specific conversation/thread id which is associated with groups of messages
  - X-GM-MSGID: allows you to search for a specific message given its account-wide unique id
  - X-GM-LABELS: string value which allows you to search for specific messages that have the given label applied
- fetch() will automatically retrieve the thread id, unique message id, and labels (named 'x-gm-thrid', 'x-gm-msgid', 'x-gm-labels' respectively)
- Additional Connection instance methods (seqno-based counterparts exist):
  - setLabels(< mixed >source, < mixed >labels, < function >callback) - (void) - Replaces labels of message(s) with labels. source can be a message UID, a message UID range (e.g. '2504:2507' or '*' or '2504:*'), or an array of message UIDs and/or message UID ranges. labels is either a single label or an array of labels. callback has 1 parameter: < Error >err.
  - addLabels(< mixed >source, < mixed >labels, < function >callback) - (void) - Adds labels to message(s). source can be a message UID, a message UID range (e.g. '2504:2507' or '*' or '2504:*'), or an array of message UIDs and/or message UID ranges. labels is either a single label or an array of labels. callback has 1 parameter: < Error >err.
  - delLabels(< mixed >source, < mixed >labels, < function >callback) - (void) - Removes labels from message(s). source can be a message UID, a message UID range (e.g. '2504:2507' or '*' or '2504:*'), or an array of message UIDs and/or message UID ranges. labels is either a single label or an array of labels. callback has 1 parameter: < Error >err.
Sort
- Server capability: SORT
- Additional Connection instance methods (seqno-based counterpart exists):
  - sort(< array >sortCriteria, < array >searchCriteria, < function >callback) - (void) - Performs a sorted search(). A seqno-based counterpart also exists for this function. callback has 2 parameters: < Error >err, < array >UIDs. Valid sortCriteria are (reverse sorting of individual criteria is done by prefixing the criteria with '-'):
    - 'ARRIVAL' - Internal date and time of the message. This differs from the ON criteria in search(), which uses just the internal date.
    - 'CC' - The mailbox of the first "cc" address.
    - 'DATE' - Message sent date and time.
    - 'FROM' - The mailbox of the first "from" address.
    - 'SIZE' - Size of the message in octets.
    - 'SUBJECT' - Base subject text.
    - 'TO' - The mailbox of the first "to" address.
Extended Search
- Server capability: ESEARCH
- Additional Connection instance methods (seqno-based counterpart exists):
  - esearch(< array >criteria, < array >options, < function >callback) - (void) - A variant of search() that can return metadata about results. callback has 2 parameters: < Error >err, < object >info. info has possible keys: 'all', 'min', 'max', 'count'. Valid options:
    - 'ALL' - Retrieves UIDs in a compact form (e.g. [2, '10:11'] instead of search()'s [2, 10, 11]) that match the criteria.
    - 'MIN' - Retrieves the lowest UID that satisfies the criteria.
    - 'MAX' - Retrieves the highest UID that satisfies the criteria.
    - 'COUNT' - Retrieves the number of messages that satisfy the criteria.
    Note: specifying no options or [] for options is the same as ['ALL']
Quota
- Server capability: QUOTA
- Additional Connection instance methods:
  - setQuota(< string >quotaRoot, < object >quotas, < function >callback) - (void) - Sets the resource limits for quotaRoot using the limits in quotas. callback has 2 parameters: < Error >err, < object >limits. limits has the same format as limits passed to getQuota()'s callback. Example quotas properties (taken from RFC2087):
    - storage - Sum of messages' (RFC822) size, in kilobytes (integer).
    - message - Number of messages (integer).
  - getQuota(< string >quotaRoot, < function >callback) - (void) - Gets the resource usage and limits for quotaRoot. callback has 2 parameters: < Error >err, < object >limits. limits is keyed on the resource name, where the values are objects with the following properties:
    - usage - < integer > - Resource usage.
    - limit - < integer > - Resource limit.
  - getQuotaRoot(< string >mailbox, < function >callback) - (void) - Gets the list of quota roots for mailbox and the resource usage and limits for each. callback has 2 parameters: < Error >err, < object >info. info is keyed on the quota root name, where the values are objects structured like limits given by getQuota(). Example info:
```
  {
    '': {
      storage: { usage: 20480, limit: 102400 }
    },
    foo: {
      storage: { usage: 1024, limit: 4096 },
      message: { usage: 14, limit: 9001 }
    }
  }
```

TODO

Several things not yet implemented in no particular order:

Support STARTTLS
Support additional IMAP commands/extensions:
- NOTIFY (via NOTIFY extension -- http://tools.ietf.org/html/rfc5465)
- STATUS addition to LIST (via LIST-STATUS extension -- http://tools.ietf.org/html/rfc5819)
- THREAD (via THREAD=ORDEREDSUBJECT and/or THREAD=REFERENCES extension(s) -- http://tools.ietf.org/html/rfc5256)

35 KiB Raw Blame History