Simple IMAP inbox
Simple IMAP inbox with watch functionality.
API
Inbox
Inbox class is the main library class
constructor
new Inbox(options);
Constructor receives one argument - object hash containing configuration options for underlying Imap object. See node-imap for available configuration options.
connect
inbox.connect(readOnly);
inbox.connect();
Connects to the IMAP server. After successful connection is made, inbox object emits connected event.
readOnly Boolean flag that indicates that inbox should be open in read-only mode. Defaults to false
Returns Promise resolved with the inbox instance
disconnect
inbox.disconnect();
Disconnects from IMAP server. After connection is closed, inbox emits disconnected event. This method has no arguments.
Returns Promise resolved with the inbox instance
destroy
inbox.destroy();
Destroys this inbox object. The object is left in unusable state. This method has no argument.
Returns The inbox instance
useGmail
inbox.useGmail();
Applies GMail IMAP options to configuration options. This method has no arguments.
Returns The inbox instance
watch
inbox.watch(options);
inbox.watch();
Starts watching for new messages. messages event is emitted for every set of received messages.
options Optional options to pass to underlying fetch method. See Inbox.fetch for more about options object.
Returns The inbox instance
unwatch
inbox.unwatch();
Stops watching for new messages.
Returns The inbox instance
fetch
inbox.fetch(offset, limit, options);
inbox.fetch(limit, options);
inbox.fetch(limit);
Fetches messages from server. Returns a promise resolved with array of found messages.
offset Integer offset of first message to fetch
limit Integer number of messages to fetch
options Object that will be passed to underlying Imap.fetch method. This object is altered - struct attribute is set to true and bodies attribute is set to ['HEADER.FIELDS (FROM TO SUBJECT DATE)', 'TEXT'] if not specified.
Returns Promise
search
inbox.search(criteria, options);
inbox.search(criteria);
Searches for messages on server. Returns a promise resolved with array of found messages.
criteria Array of valid IMAP search criteria.
options Object that will be passed to underlying Imap.fetch method. See Inbox.fetch for more about options object.
Returns Promise
searchForUID
inbox.searchForUID(criteria);
Searches for message UIDs on server. Returns a promise resolved with array of found message UIDs.
criteria Array of valid IMAP search criteria.
Returns Promise
fetchByUID
inbox.fetchByUID(uids, options);
inbox.fetchByUID(uids);
Fetches messages from server by UIDs. Returns a promise resolved with array of found messages.
uids Either a string specifiing UID range (1:10, 1:*), array of UID range strings or array of UIDs
options Object that will be passed to underlying Imap.fetch method. See Inbox.fetch for more about options object.
Returns Promise
imap
inbox.imap;
Underlying Imap instance
inbox
inbox.inbox;
Instance of Box class from node-imap library. See node-imap for more information on this class. This property is not null after an inbox has been opened via Inbox.connect method.
Message
Message represents single message obtained from Inbox.
headers
message.headers;
Object containing message headers.
body
message.body;
String containing message body in plain text.
subject
message.subject;
String subject of email message.
recipients
message.recipients;
Array of recipients. Each entry is an object containing name (possibly empty) and address properties.
links
message.links;
Array of links parsed from message body.
Testing
To run the unit tests, you can simply run
$ grunt test
You can use
$ grunt test:live
for development purposes. This task will watch for changes in source and test files and will run the tests once something has changed.