Skip to main content

SELECT folder

This function selects a folder that mail commands get executed in.

It is absolutely crucial to run this before running any mail commands (or pass the folder prop to fetchEmails()). Doing so otherwise will cause an error.

Usage​

let mailbox = await imap.selectFolder("INBOX")

Response​

The response is a typed MailboxInfo:

type MailboxInfo = {
    emails: number,             // number of messages (EXISTS)
    recent: number,             // number of recent messages (RECENT)
    unseen?: number,            // OK [UNSEEN n]
    uidNext?: number,           // OK [UIDNEXT n]
    uidValidity?: number,       // OK [UIDVALIDITY n]
    highestModSeq?: number,     // OK [HIGHESTMODSEQ n] (CONDSTORE, RFC 7162)
    nomodSeq?: boolean,         // true if the mailbox has no modification sequences
    flags: string[],            // flags supported by the mailbox, e.g. ["Answered", "Flagged", "Seen"]
    permanentFlags: string[],   // flags that can be stored permanently, e.g. ["Seen", "Deleted", "*"]
    readOnly: boolean           // true if the mailbox was opened read-only
}
{
    emails: 78,
    recent: 0,
    unseen: 1,
    uidNext: 92,
    uidValidity: 1687639849,
    highestModSeq: 242,
    flags: [ 'Answered', 'Flagged', 'Draft', 'Deleted', 'Seen' ],
    permanentFlags: [ 'Answered', 'Flagged', 'Draft', 'Deleted', 'Seen', '*' ],
    readOnly: false
}
info

The unseen, uidNext, uidValidity, highestModSeq and permanentFlags fields are optional because not every server reports them (or reports them differently). Some servers (e.g. Dovecot) send them as untagged * OK [...] lines, which is handled.

EXAMINE (read-only select)​

examine() is identical to selectFolder() but opens the mailbox read-only (RFC 9051 §6.3.3) — no changes to the mailbox, including flags, are permitted. It returns the same MailboxInfo (with readOnly: true).

const mailbox = await imap.examine("INBOX")

CLOSE & UNSELECT (deselect)​

await imap.closeMailbox()   // CLOSE: expunges \Deleted messages, then deselects
await imap.unselect()       // UNSELECT: deselects without expunging

Both reset the selected-folder state: after them, mail commands require a new selectFolder()/examine() call. Note the difference from logout() — these keep the connection (and authentication) alive.