| FazBrowse GitHub Viewer | Trending | | Home |
| Tools: [Download Repo ZIP] [Original HTTPS Page] |
| Name | Name | Last commit date | ||
|---|---|---|---|---|
node-imap is an IMAP module for node.js that provides an asynchronous interface for communicating with an IMAP mail server.
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). If you are in need of this kind of extra functionality, check out andris9's mimelib module. Also check out his mailparser module, which comes in handy after you fetch() a 'full' raw email message with this module.
npm install imap
This example fetches the 'date', 'from', 'to', 'subject' message headers and the message structure of all unread messages in the Inbox since May 20, 2010:
var ImapConnection = require('./imap').ImapConnection, util = require('util'),
imap = new ImapConnection({
username: 'mygmailname@gmail.com',
password: 'mygmailpassword',
host: 'imap.gmail.com',
port: 993,
secure: true
});
function die(err) {
console.log('Uh oh: ' + err);
process.exit(1);
}
var box, cmds, next = 0, cb = function(err) {
if (err)
die(err);
else if (next < cmds.length)
cmds[next++].apply(this, Array.prototype.slice.call(arguments).slice(1));
};
cmds = [
function() { imap.connect(cb); },
function() { imap.openBox('INBOX', false, cb); },
function(result) { box = result; imap.search([ 'UNSEEN', ['SINCE', 'May 20, 2010'] ], cb); },
function(results) {
var fetch = imap.fetch(results, { request: { headers: ['from', 'to', 'subject', 'date'] } });
fetch.on('message', function(msg) {
console.log('Got message: ' + util.inspect(msg, false, 5));
msg.on('data', function(chunk) {
console.log('Got message chunk of size ' + chunk.length);
});
msg.on('end', function() {
console.log('Finished message: ' + util.inspect(msg, false, 5));
});
});
fetch.on('end', function() {
console.log('Done fetching all messages!');
imap.logout(cb);
});
}
];
cb();
node-imap exposes one object: ImapConnection.
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 the IMAP spec (that may be added/removed to/from messages):
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 Array first. Additional custom flags may be provided by the server. If available, these will also be listed in the mailbox's permFlags Array.
alert(String) - Fires when the server issues an alert (e.g. "the server is going down for maintenance"). The supplied String is the text of the alert message.
mail(Integer) - Fires when new mail arrives in the currently open mailbox. The supplied Integer specifies the number of new messages.
deleted(Integer) - Fires when a message is deleted from another IMAP connection's session. The Integer value is the sequence number (instead of the unique ID) of the message that was deleted. The sequence numbers of all messages higher than this value MUST be decremented by 1 in order to stay synchronized with the server and to keep continuity of sequence numbers.
msgupdate(ImapMessage) - Fires when a message's flags have changed, generally from another IMAP connection's session. With that in mind, the only available properties in this case will almost always be 'seqno' and 'flags' (and obviously no 'data' or 'end' events will be emitted on the object).
close(Boolean) - Fires when the connection is completely closed (similar to net.Stream's close event). The specified Boolean indicates whether the connection was terminated due to a transmission error or not.
end() - Fires when the connection is ended (similar to net.Stream's end event).
error(Error) - Fires when an exception/error occurs (similar to net.Stream's error event). The given Error object represents the error raised.
capabilities - An Array containing the capabilities of the server.
delim - A String containing the (top-level) mailbox hierarchy delimiter. If the server does not support mailbox hierarchies and only a flat list, this value will be Boolean false.
namespaces - An Object containing 3 properties, one for each namespace type: personal (mailboxes that belong to the logged in user), other (mailboxes that belong to other users that the logged in user has access to), and shared (mailboxes that are accessible by any logged in user). The value of each of these properties is an Array of namespace Objects containing necessary information about each available namespace. There should always be one entry (although the IMAP spec allows for more, it doesn't seem to be very common) in the personal namespace list (if the server supports namespaces) with a blank namespace prefix. Each namespace Object has the following format (with example values):
{ prefix: '' // A String containing the prefix to use to access mailboxes in this namespace
, delim: '/' // 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
}
]
}
Note: Message ID sets for message ID range arguments are not guaranteed to be contiguous.
(constructor)([Object]) - ImapConnection - Creates and returns a new instance of ImapConnection using the specified configuration object. Valid properties of the passed in object are:
connect(Function) - (void) - Attempts to connect and log into the IMAP server. The Function parameter is the callback with one parameter: the error (null if none).
logout(Function) - (void) - Closes the connection to the server. The Function parameter is the callback.
openBox(String[, Boolean], Function) - (void) - Opens a specific mailbox that exists on the server. The String parameter is the name (including any necessary prefix/path) of the mailbox to open. The optional Boolean parameter specifies if the mailbox should be opened in read-only mode (defaults to false). The Function parameter is the callback with two parameters: the error (null if none), and the Box object of the newly opened mailbox.
closeBox(Function) - (void) - Closes the currently open mailbox. Any messages marked as Deleted in the mailbox will be removed if the mailbox was NOT opened in read-only mode. Also, logging out or opening another mailbox without closing the current one first will NOT cause deleted messages to be removed. The Function parameter is the callback with one parameter: the error (null if none).
addBox(String, Function) - (void) - Creates a new mailbox on the server. The String parameter is the name (including any necessary prefix/path) of the new mailbox to create. The Function parameter is the callback with one parameter: the error (null if none).
delBox(String, Function) - (void) - Removes a specific mailbox that exists on the server. The String parameter is the name (including any necessary prefix/path) of the mailbox to remove. The Function parameter is the callback with one parameter: the error (null if none).
renameBox(String, String, Function) - (void) - Renames a specific mailbox that exists on the server. The first String parameter is the name (including any necessary prefix/path) of the existing mailbox. The second String parameter is the name (including any necessary prefix/path) of the new mailbox. The Boolean parameter specifies whether to open the mailbox in read-only mode or not. The Function parameter is the callback with two parameters: the error (null if none), and the Box object of the newly renamed mailbox. Note: Renaming the 'INBOX' mailbox will instead cause all messages in 'INBOX' to be moved to the new mailbox.
getBoxes([String, ]Function) - (void) - Obtains the full list of mailboxes. The optional String parameter is the namespace prefix to use (defaults to the main personal namespace). The Function parameter is the callback with two parameters: the error (null if none), and an Object with the following format (with example values):
{ INBOX: // mailbox name
{ attribs: [] // mailbox attributes. An attribute of 'NOSELECT' indicates the mailbox cannot be opened
, delim: '/' // hierarchy delimiter for accessing this mailbox's direct children. This should usually be the same as ImapConnection.delim (?)
, children: null // an Object containing another structure similar in format to this top level, null if no children
, parent: null // pointer to parent mailbox, null if at the top level
}
, Work:
{ attribs: []
, delim: '/'
, children: null
, parent: null
}
, '[Gmail]':
{ attribs: [ 'NOSELECT' ]
, delim: '/'
, children:
{ 'All Mail':
{ attribs: []
, delim: '/'
, children: null
, parent: [Circular]
}
, Drafts:
{ attribs: []
, delim: '/'
, children: null
, parent: [Circular]
}
, 'Sent Mail':
{ attribs: []
, delim: '/'
, children: null
, parent: [Circular]
}
, Spam:
{ attribs: []
, delim: '/'
, children: null
, parent: [Circular]
}
, Starred:
{ attribs: []
, delim: '/'
, children: null
, parent: [Circular]
}
, Trash:
{ attribs: []
, delim: '/'
, children: null
, parent: [Circular]
}
}
, parent: null
}
}
removeDeleted(Function) - (void) - Permanently removes (EXPUNGEs) all messages flagged as Deleted in the mailbox that is currently open. The Function parameter is the callback with one parameter: the error (null if none). 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(Buffer/String, [Object,] Function) - (void) - Appends a message to selected mailbox. The first parameter is a string or Buffer containing an RFC-822 compatible MIME message. The Function parameter is the callback with one parameter: the error (null if none). The second parameter is an options object. Valid options are:
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 numbers instead of unique ids, conn.seq.fetch() fetches by sequence number(s) instead of unique ids, etc):
search(Array, Function) - (void) - Searches the currently open mailbox for messages using specific criterion. The Function parameter is the callback with two parameters: the error (null if none) and an Array containing the message IDs matching the search criterion. The Array parameter is a list of Arrays containing the criterion (and any required arguments) to be used. Prefix the criteria name with an "!" to negate. For example, to search for unread messages since April 20, 2010 you could use: [ 'UNSEEN', ['SINCE', 'April 20, 2010'] ]. To search for messages that are EITHER unread OR are dated April 20, 2010 or later, you could use: [ ['OR', 'UNSEEN', ['SINCE', 'April 20, 2010'] ] ].
fetch(Integer/String/Array, Object) - ImapFetch - Fetches the message(s) identified by the first parameter, in the currently open mailbox. The first parameter can either be an Integer for a single message ID, a String for a message ID range (e.g. '2504:2507' or '*' or '2504:*'), or an Array containing any number of the aforementioned Integers and/or Strings. The second (Object) parameter is a set of options used to determine how and what exactly to fetch. The valid options are:
copy(Integer/String/Array, String, Function) - (void) - Copies the message(s) with the message ID(s) identified by the first parameter, in the currently open mailbox, to the mailbox specified by the second parameter. The first parameter can either be an Integer for a single message ID, a String for a message ID range (e.g. '2504:2507' or '*' or '2504:*'), or an Array containing any number of the aforementioned Integers and/or Strings. The Function parameter is the callback with one parameter: the error (null if none).
move(Integer/String/Array, String, Function) - (void) - Moves the message(s) with the message ID(s) identified by the first parameter, in the currently open mailbox, to the mailbox specified by the second parameter. The first parameter can either be an Integer for a single message ID, a String for a message ID range (e.g. '2504:2507' or '*' or '2504:*'), or an Array containing any number of the aforementioned Integers and/or Strings. The Function parameter is the callback with one parameter: the error (null if none). Note: The message in the destination mailbox will have a new message ID.
addFlags(Integer/String/Array, String/Array, Function) - (void) - Adds the specified flag(s) to the message(s) identified by the first parameter. The first parameter can either be an Integer for a single message ID, a String for a message ID range (e.g. '2504:2507' or '*' or '2504:*'), or an Array containing any number of the aforementioned Integers and/or Strings. The second parameter can either be a String containing a single flag or can be an Array of flags. The Function parameter is the callback with one parameter: the error (null if none).
delFlags(Integer/String/Array, String/Array, Function) - (void) - Removes the specified flag(s) from the message(s) identified by the first parameter. The first parameter can either be an Integer for a single message ID, a String for a message ID range (e.g. '2504:2507' or '*' or '2504:*'), or an Array containing any number of the aforementioned Integers and/or Strings. The second parameter can either be a String containing a single flag or can be an Array of flags. The Function parameter is the callback with one parameter: the error (null if none).
addKeywords(Integer/String/Array, String/Array, Function) - (void) - Adds the specified keyword(s) to the message(s) identified by the first parameter. The first parameter can either be an Integer for a single message ID, a String for a message ID range (e.g. '2504:2507' or '*' or '2504:*'), or an Array containing any number of the aforementioned Integers and/or Strings. The second parameter can either be a String containing a single keyword or can be an Array of keywords. The Function parameter is the callback with one parameter: the error (null if none).
delKeywords(Integer/String/Array, String/Array, Function) - (void) - Removes the specified keyword(s) from the message(s) identified by the first parameter. The first parameter can either be an Integer for a single message ID, a String for a message ID range (e.g. '2504:2507' or '*' or '2504:*'), or an Array containing any number of the aforementioned Integers and/or Strings. The second parameter can either be a String containing a single keyword or can be an Array of keywords. The Function parameter is the callback with one parameter: the error (null if none).
Several things not yet implemented in no particular order:
| Back | FazBrowse Home | New Git URL |