Constructor
new ImapFlow(options)
Parameters:
Name | Type | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
IMAP connection options Properties
|
Extends
- EventEmitter
Members
authenticated :String|Boolean
Currently authenticated user or false
if mailbox is not open
or true
if connection was authenticated by PREAUTH
capabilities :Map.<string, (boolean|number)>
Active IMAP capabilities. Value is either true
for togglabe capabilities (eg. UIDPLUS
)
or a number for capabilities with a value (eg. APPENDLIMIT
)
emitLogs :Boolean
If true
then in addition of sending data to logger, ImapFlow emits 'log' events with the same data
enabled :Set.<string>
Enabled capabilities. Usually CONDSTORE
and UTF8=ACCEPT
if server supports these.
id :String
Instance ID for logs
idling :Boolean
Is current mailbox idling (true
) or not (false
)
mailbox :MailboxObject|Boolean
Currently selected mailbox or false
if mailbox is not open
secureConnection :Boolean
Is the connection currently encrypted or not
serverInfo :IdInfoObject|null
Server identification info. Available after successful connect()
.
If server does not provide identification info then this value is null
.
Example
await client.connect();
console.log(client.serverInfo.vendor);
usable :Boolean
Is the connection currently usable or not
version
Current module version as a static class property
Properties:
Name | Type | Description |
---|---|---|
version |
String |
Module version |
Methods
(async) append(path, content, flagsopt, idateopt) → {Promise.<AppendResponseObject>}
Appends a new message to a mailbox
Parameters:
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
path |
String |
Mailbox path to upload the message to (unicode string) |
||
content |
string | Buffer |
RFC822 formatted email message |
||
flags |
Array.<string> |
<optional> |
an array of flags to be set for the uploaded message |
|
idate |
Date | string |
<optional> |
now |
internal date to be set for the message |
close()
Closes TCP connection without notifying the server.
(async) connect() → {Promise.<void>}
Initiates a connection against IMAP server. Throws if anything goes wrong. This is something you have to call before you can run any IMAP commands
Throws:
Will throw an error if connection or authentication fails
(async) download(range, partopt, optionsopt) → {Promise.<DownloadObject>}
Download either full rfc822 formated message or a specific bodystructure part as a Stream. Bodystructure parts are decoded so the resulting stream is a binary file. Text content is automatically converted to UTF-8 charset.
Parameters:
Name | Type | Attributes | Description | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
range |
SequenceString |
UID or sequence number for the message to fetch |
|||||||||||||||||||||
part |
String |
<optional> |
If not set then downloads entire rfc822 formatted message, otherwise downloads specific bodystructure part |
||||||||||||||||||||
options |
Object |
<optional> |
Properties
|
Example
let mailbox = await client.mailboxOpen('INBOX');
// download body part nr '1.2' from latest message
let {meta, content} = await client.download('*', '1.2');
content.pipe(fs.createWriteStream(meta.filename));
(async) downloadMany(range, parts, optionsopt) → {Promise.<Object>}
Fetch multiple attachments as Buffer values
Parameters:
Name | Type | Attributes | Description | ||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
range |
SequenceString |
UID or sequence number for the message to fetch |
|||||||||
parts |
String |
A list of bodystructure parts |
|||||||||
options |
Object |
<optional> |
Properties
|
Example
let mailbox = await client.mailboxOpen('INBOX');
// download body parts '2', and '3' from all messages in the selected mailbox
let response = await client.downloadMany('*', ['2', '3']);
process.stdout.write(response[2].content)
process.stdout.write(response[3].content)
(async, generator) fetch(range, query, optionsopt)
Fetch messages from currently opened mailbox
Parameters:
Name | Type | Attributes | Description | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
range |
SequenceString | Array.<Number> | SearchObject |
Range of messages to fetch |
|||||||||||||||||||||
query |
FetchQueryObject |
Fetch query |
|||||||||||||||||||||
options |
Object |
<optional> |
Properties
|
Example
let mailbox = await client.mailboxOpen('INBOX');
// fetch UID for all messages in a mailbox
for await (let msg of client.fetch('1:*', {uid: true})){
console.log(msg.uid);
// NB! You can not run any IMAP commands in this loop
// otherwise you will end up in a deadloop
}
(async) fetchOne(seq, query, optionsopt) → {Promise.<FetchMessageObject>}
Fetch a single message from currently opened mailbox
Parameters:
Name | Type | Attributes | Description | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
seq |
SequenceString |
Single UID or sequence number of the message to fetch for |
||||||||||||||||
query |
FetchQueryObject |
Fetch query |
||||||||||||||||
options |
Object |
<optional> |
Properties
|
Example
let mailbox = await client.mailboxOpen('INBOX');
// fetch UID for the last email in the selected mailbox
let lastMsg = await client.fetchOne('*', {uid: true})
console.log(lastMsg.uid);
(async) getMailboxLock(path, optionsopt) → {Promise.<MailboxLockObject>}
Opens a mailbox if not already open and returns a lock. Next call to getMailboxLock()
is queued
until previous lock is released. This is suggested over mailboxOpen()
as
getMailboxLock()
gives you a weak transaction while mailboxOpen()
has no guarantees whatsoever that another
mailbox is opened while you try to call multiple fetch or store commands.
Parameters:
Name | Type | Attributes | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
path |
string | array |
Path for the mailbox to open |
|||||||||||
options |
Object |
<optional> |
optional options Properties
|
Throws:
Will throw an error if mailbox does not exist or can not be opened
Example
let lock = await client.getMailboxLock('INBOX');
try {
// do something in the mailbox
} finally {
// use finally{} to make sure lock is released even if exception occurs
lock.release();
}
(async) getQuota(pathopt) → {Promise.<(QuotaResponse|Boolean)>}
Returns current quota
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
path |
String |
<optional> |
Optional mailbox path if you want to check quota for specific folder |
Example
let quota = await client.getQuota();
console.log(quota.storage.used, quota.storage.available)
(async) idle() → {Promise.<Boolean>}
Starts listening for new or deleted messages from the currently opened mailbox. Only required if ImapFlow#disableAutoIdle
is set to true
otherwise IDLE is started by default on connection inactivity. NB! If idle()
is called manually then it does not
return until IDLE is finished which means you would have to call some other command out of scope.
(async) list(optionsopt) → {Promise.<Array.<ListResponse>>}
Lists available mailboxes as an Array
Parameters:
Name | Type | Attributes | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
Object |
<optional> |
defines additional listing options Properties
|
(async) listTree() → {Promise.<ListTreeResponse>}
Lists available mailboxes as a tree structured object
Example
let tree = await client.listTree();
tree.folders.forEach(mailbox=>console.log(mailbox.path));
(async) logout() → {Promise.<void>}
Graceful connection close by sending logout command to server. TCP connection is closed once command is finished.
(async) mailboxClose() → {Promise.<Boolean>}
Closes a previously opened mailbox
(async) mailboxCreate(path) → {Promise.<MailboxCreateResponse>}
Creates a new mailbox folder and sets up subscription for the created mailbox. Throws on error.
Parameters:
Name | Type | Description |
---|---|---|
path |
string | array |
Full mailbox path. Unicode is allowed. If value is an array then it is joined using current delimiter symbols. Namespace prefix is added automatically if required. |
Throws:
Will throw an error if mailbox can not be created
Example
let info = await client.mailboxCreate(['parent', 'child']);
console.log(info.path);
// "INBOX.parent.child" // assumes "INBOX." as namespace prefix and "." as delimiter
(async) mailboxDelete(path) → {Promise.<MailboxDeleteResponse>}
Deletes a mailbox. Throws on error.
Parameters:
Name | Type | Description |
---|---|---|
path |
string | array |
Path for the mailbox to delete. Unicode is allowed. If value is an array then it is joined using current delimiter symbols. Namespace prefix is added automatically if required. |
Throws:
Will throw an error if mailbox does not exist or can not be deleted
Example
let info = await client.mailboxDelete('Important stuff ❗️');
console.log(info.path);
// "INBOX.Important stuff ❗️" // assumes "INBOX." as namespace prefix
(async) mailboxOpen(path, optionsopt) → {Promise.<MailboxObject>}
Opens a mailbox to access messages. You can perform message operations only against an opened mailbox.
Using getMailboxLock()
instead of mailboxOpen()
is preferred. Both do the same thing
but next getMailboxLock()
call is not executed until previous one is released.
Parameters:
Name | Type | Attributes | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
path |
string | array |
Path for the mailbox to open |
|||||||||||
options |
Object |
<optional> |
optional options Properties
|
Throws:
Will throw an error if mailbox does not exist or can not be opened
Example
let mailbox = await client.mailboxOpen('Important stuff ❗️');
console.log(mailbox.exists);
// 125
(async) mailboxRename(path, newPath) → {Promise.<MailboxRenameResponse>}
Renames a mailbox. Throws on error.
Parameters:
Name | Type | Description |
---|---|---|
path |
string | array |
Path for the mailbox to rename. Unicode is allowed. If value is an array then it is joined using current delimiter symbols. Namespace prefix is added automatically if required. |
newPath |
string | array |
New path for the mailbox |
Throws:
Will throw an error if mailbox does not exist or can not be renamed
Example
let info = await client.mailboxRename('parent.child', 'Important stuff ❗️');
console.log(info.newPath);
// "INBOX.Important stuff ❗️" // assumes "INBOX." as namespace prefix
(async) mailboxSubscribe(path) → {Promise.<Boolean>}
Subscribes to a mailbox
Parameters:
Name | Type | Description |
---|---|---|
path |
string | array |
Path for the mailbox to subscribe to. Unicode is allowed. If value is an array then it is joined using current delimiter symbols. Namespace prefix is added automatically if required. |
(async) mailboxUnsubscribe(path) → {Promise.<Boolean>}
Unsubscribes from a mailbox
Parameters:
Name | Type | Description |
---|---|---|
path |
string | array |
Path for the mailbox to unsubscribe from. Unicode is allowed. If value is an array then it is joined using current delimiter symbols. Namespace prefix is added automatically if required. |
(async) messageCopy(range, destination, optionsopt) → {Promise.<CopyResponseObject>}
Copies messages from current mailbox to destination mailbox
Parameters:
Name | Type | Attributes | Description | ||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
range |
SequenceString | Array.<Number> | SearchObject |
Range of messages to copy |
|||||||||
destination |
String |
Mailbox path to copy the messages to |
|||||||||
options |
Object |
<optional> |
Properties
|
Example
await client.mailboxOpen('INBOX');
// copy all messages to a mailbox called "Backup" (must exist)
let result = await client.messageCopy('1:*', 'Backup');
console.log('Copied %s messages', result.uidMap.size);
(async) messageDelete(range, optionsopt) → {Promise.<Boolean>}
Delete messages from currently opened mailbox. Method does not indicate info about deleted messages,
instead you should be using ImapFlow#expunge
event for this
Parameters:
Name | Type | Attributes | Description | ||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
range |
SequenceString | Array.<Number> | SearchObject |
Range to filter the messages |
|||||||||
options |
Object |
<optional> |
Properties
|
Example
let mailbox = await client.mailboxOpen('INBOX');
// delete all seen messages
await client.messageDelete({seen: true});
(async) messageFlagsAdd(range, Array, optionsopt) → {Promise.<Boolean>}
Adds flags for a message or message range
Parameters:
Name | Type | Attributes | Description | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
range |
SequenceString | Array.<Number> | SearchObject |
Range to filter the messages |
|||||||||||||||||||||
Array |
Array.<string> |
of flags to set. Only flags that are permitted to set are used, other flags are ignored |
|||||||||||||||||||||
options |
Object |
<optional> |
Properties
|
Example
let mailbox = await client.mailboxOpen('INBOX');
// mark all unseen messages as seen (and keep other flags as is)
await client.messageFlagsAdd({seen: false}, ['\Seen]);
(async) messageFlagsRemove(range, Array, optionsopt) → {Promise.<Boolean>}
Remove specific flags from a message or message range
Parameters:
Name | Type | Attributes | Description | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
range |
SequenceString | Array.<Number> | SearchObject |
Range to filter the messages |
|||||||||||||||||||||
Array |
Array.<string> |
of flags to remove. Only flags that are permitted to set are used, other flags are ignored |
|||||||||||||||||||||
options |
Object |
<optional> |
Properties
|
Example
let mailbox = await client.mailboxOpen('INBOX');
// mark all seen messages as unseen by removing \\Seen flag
await client.messageFlagsRemove({seen: true}, ['\Seen]);
(async) messageFlagsSet(range, Array, optionsopt) → {Promise.<Boolean>}
Sets flags for a message or message range
Parameters:
Name | Type | Attributes | Description | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
range |
SequenceString | Array.<Number> | SearchObject |
Range to filter the messages |
|||||||||||||||||||||
Array |
Array.<string> |
of flags to set. Only flags that are permitted to set are used, other flags are ignored |
|||||||||||||||||||||
options |
Object |
<optional> |
Properties
|
Example
let mailbox = await client.mailboxOpen('INBOX');
// mark all unseen messages as seen (and remove other flags)
await client.messageFlagsSet({seen: false}, ['\Seen]);
(async) messageMove(range, destination, optionsopt) → {Promise.<CopyResponseObject>}
Moves messages from current mailbox to destination mailbox
Parameters:
Name | Type | Attributes | Description | ||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
range |
SequenceString | Array.<Number> | SearchObject |
Range of messages to move |
|||||||||
destination |
String |
Mailbox path to move the messages to |
|||||||||
options |
Object |
<optional> |
Properties
|
Example
await client.mailboxOpen('INBOX');
// move all messages to a mailbox called "Trash" (must exist)
let result = await client.messageMove('1:*', 'Trash');
console.log('Moved %s messages', result.uidMap.size);
(async) noop() → {Promise.<void>}
Performs a no-op call against server
(async) search(query, optionsopt) → {Promise.<Array.<Number>>}
Search messages from currently opened mailbox
Parameters:
Name | Type | Attributes | Description | ||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
query |
SearchObject |
Query to filter the messages |
|||||||||
options |
Object |
<optional> |
Properties
|
Example
let mailbox = await client.mailboxOpen('INBOX');
// find all unseen messages
let list = await client.search({seen: false});
// use OR modifier (array of 2 or more search queries)
let list = await client.search({
seen: false,
or: [
{flagged: true},
{from: 'andris'},
{subject: 'test'}
]});
(async) setFlagColor(range, The, optionsopt) → {Promise.<Boolean>}
Sets a colored flag for an email. Only supported by mail clients like Apple Mail
Parameters:
Name | Type | Attributes | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
range |
SequenceString | Array.<Number> | SearchObject |
Range to filter the messages |
|||||||||||||
The |
string |
color to set. One of 'red', 'orange', 'yellow', 'green', 'blue', 'purple', and 'grey' |
|||||||||||||
options |
Object |
<optional> |
Properties
|
Example
let mailbox = await client.mailboxOpen('INBOX');
// add a purple flag for all emails
await client.setFlagColor('1:*', 'Purple');
(async) status(path, query) → {Promise.<StatusObject>}
Requests the status of the indicated mailbox. Only requested status values will be returned.
Parameters:
Name | Type | Description | |||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
path |
String |
mailbox path to check for (unicode string) |
|||||||||||||||||||||
query |
Object |
defines requested status items Properties
|
Example
let status = await client.status('INBOX', {unseen: true});
console.log(status.unseen);
// 123
Events
close
Connection close event. NB! ImapFlow does not handle reconncts automatically. So whenever a 'close' event occurs you must create a new connection yourself.
error :Error
Error event. In most cases getting an error event also means that connection is closed and pending operations should return with a failure.
exists :Object
Message count in currently opened mailbox changed
Properties:
Name | Type | Description |
---|---|---|
path |
String |
mailbox path this event applies to |
count |
Number |
updated count of messages |
prevCount |
Number |
message count before this update |
Example
client.on('exists', data=>{
console.log(`Message count in "${data.path}" is ${data.count}`);
});
expunge :Object
Deleted message sequence number in currently opened mailbox. One event is fired for every deleted email.
Properties:
Name | Type | Description |
---|---|---|
path |
String |
mailbox path this event applies to |
seq |
Number |
sequence number of deleted message |
Example
client.on('expunge', data=>{
console.log(`Message #${data.seq} was deleted from "${data.path}"`);
});
flags :Object
Flags were updated for a message. Not all servers fire this event.
Properties:
Name | Type | Attributes | Description |
---|---|---|---|
path |
String |
mailbox path this event applies to |
|
seq |
Number |
sequence number of updated message |
|
uid |
Number |
<optional> |
UID number of updated message (if server provided this value) |
modseq |
BigInt |
<optional> |
Updated modseq number for the mailbox (if server provided this value) |
flags |
Set.<string> |
A set of all flags for the updated message |
Example
client.on('flags', data=>{
console.log(`Flag set for #${data.seq} is now "${Array.from(data.flags).join(', ')}"`);
});
log :Object
Log event if emitLogs=true
mailboxClose :MailboxObject
Mailbox was closed
Example
client.on('mailboxClose', mailbox => {
console.log(`Mailbox ${mailbox.path} was closed`);
});
mailboxOpen :MailboxObject
Mailbox was opened