FETCH email(s)
A folder must be selected (see "SELECT folder") before running this function — or pass the folder prop to select it automatically.
This function fetches emails from the selected folder, parses the headers and — when fetchBody is enabled — the full MIME structure (text/plain, text/html and attachments).
Usage
export type FetchEmailsProps = {
limit: [number, number] | number, // range of sequence numbers (or UIDs with useUid), or a single one
folder?: string, // optional, selects it automatically if different from the selected folder
fetchBody?: boolean, // default true. If false, only the header fields are fetched
byteLimit?: number, // not recommended, may break MIME parsing
useUid?: boolean, // if true, limit is interpreted as a UID range (UID FETCH)
peek?: boolean // default true. If false, fetching sets the "\Seen" flag
}
// Full messages, MIME-parsed (sequence numbers 1 through 10, doesn't set \Seen)
let emails = await imap.fetchEmails({
limit: [1, 10],
fetchBody: true
})
// Headers only
let headers = await imap.fetchEmails({ limit: [1, 10], fetchBody: false })
// By UID (marks the message as \Seen, because peek is false)
let byUid = await imap.fetchEmails({
limit: [42, 42],
useUid: true,
peek: false
})
Response
The type for the response of this function is:
export type Email = {
uid: number,
seq: number, // sequence number in the selected folder (always a sequence number, even with useUid)
flags: string[], // e.g. ["Seen", "Flagged"] (no backslash)
internalDate: Date, // INTERNALDATE of the message
size: number, // RFC822.SIZE in bytes
from: string[], // decoded addresses, e.g. ['"Jane Doe" <[email protected]>']
to: string[],
cc: string[],
subject: string, // MIME-encoded words decoded
messageID: string,
contentType: string,
headers: Record<string, string>,// all parsed headers (lowercased, unfolded, MIME-decoded)
rawHeaders: string,
body: {
text?: string, // decoded text/plain body, if present
html?: string, // decoded text/html body, if present
raw: string // the raw body section (the full raw message when fetchBody is true)
},
attachments: Attachment[], // parsed MIME attachments (empty when fetchBody is false)
raw: string // the full raw message (or the raw header section)
}
export type Attachment = {
filename: string,
mimeType: string, // e.g. "application/pdf"
size: number, // decoded size in bytes
encoding: string, // original Content-Transfer-Encoding, e.g. "base64"
content: string, // decoded content (charset-decoded for text/*, byte-preserving otherwise)
contentBase64: string, // decoded content as base64
contentId?: string, // for inline images
isInline: boolean // true if marked inline (e.g. embedded images)
}
Example response:
[
{
uid: 17,
seq: 1,
flags: [ '$NotJunk' ],
internalDate: 2023-06-24T20:50:50.000Z,
size: 52224,
from: [ '[email protected]' ],
to: [ '[email protected]' ],
cc: [],
subject: 'Sveicināti inbox.lv!',
messageID: '<[email protected]>',
contentType: 'multipart/alternative; boundary=C19HvGcu',
headers: { subject: 'Sveicināti inbox.lv!', from: '[email protected]', ... },
rawHeaders: 'Return-Path: <[email protected]>\r\nReceived: ...',
body: {
text: 'Laba izvēle! Laipni lūdzam inbox.lv...',
html: '<html>...',
raw: 'Return-Path: <[email protected]>\r\n...'
},
attachments: [],
raw: 'Return-Path: <[email protected]>\r\n...'
}
]
Bodies are charset-decoded (UTF-8, latin-1, windows-1252, ...) and transfer-encoding-decoded (base64, quoted-printable). Multipart messages (mixed/alternative/related) are parsed recursively, so nested text parts and inline images are handled correctly.
Large messages that the server splits into multiple literals (BODY[]<offset> {N} responses) are re-assembled correctly. With useUid, the uid field carries the message UID while seq remains the sequence number in the selected folder.
byteLimit fetches only the first N octets of each message via a partial fetch (BODY[]<0.N>) — the returned body.raw will be truncated, which may break MIME parsing. Prefer fetching full messages and filtering by size instead.