Class ImapAbstract

constructor

• new Imap(): Imap

  Returns Imap

Abstractconnect

• connect(options: ImapConnectOptions): Promise<string>

  Opens a connection to an IMAP server and authenticates.

  Parameters

  • options: ImapConnectOptions

    Server address, port, TLS setting, and credentials

  Returns Promise<string>

  An opaque session handle for subsequent operations

  Throws

  If the host is not in the declared hosts list, connection fails, or auth fails

AbstractlistMailboxes

• listMailboxes(session: string): Promise<ImapMailbox[]>

  Lists all mailboxes (folders) on the server.

  Parameters

  • session: string

    Session handle from connect()

  Returns Promise<ImapMailbox[]>

  Array of mailbox descriptors

AbstractselectMailbox

• selectMailbox(session: string, mailbox: string): Promise<ImapMailboxStatus>

  Selects a mailbox for subsequent search/fetch/flag operations.

  Parameters

  • session: string

    Session handle from connect()

  • mailbox: string

    Mailbox name (e.g. "INBOX")

  Returns Promise<ImapMailboxStatus>

  Mailbox status including message count and UID validity

Abstractsearch

• search(session: string, criteria: ImapSearchCriteria): Promise<number[]>

  Searches for messages matching the given criteria in the selected mailbox.

  All criteria fields are ANDed together. Returns UIDs (not sequence numbers).

  Parameters

  • session: string

    Session handle from connect()

  • criteria: ImapSearchCriteria

    Search criteria (all optional, ANDed)

  Returns Promise<number[]>

  Array of matching message UIDs

AbstractfetchMessages

• fetchMessages(
      session: string,
      uids: number[],
      options?: ImapFetchOptions,
  ): Promise<ImapMessage[]>

  Fetches message data for the given UIDs.

  By default fetches headers only. Set body: true in options to include message body content. The implementation handles MIME decoding internally.

  Parameters

  • session: string

    Session handle from connect()

  • uids: number[]

    Array of message UIDs to fetch

  • Optionaloptions: ImapFetchOptions

    What to fetch (headers, body, body type)

  Returns Promise<ImapMessage[]>

  Array of message objects with requested fields populated

AbstractsetFlags

• setFlags(
      session: string,
      uids: number[],
      flags: string[],
      operation: ImapFlagOperation,
  ): Promise<void>

  Modifies flags on messages.

  Common flags: "\Seen" (read), "\Flagged" (starred), "\Deleted" (marked for deletion).

  Parameters

  • session: string

    Session handle from connect()

  • uids: number[]

    Array of message UIDs to modify

  • flags: string[]

    Flags to add/remove/set (e.g. ["\Seen"])

  • operation: ImapFlagOperation

    "add", "remove", or "set" (replace all flags)

  Returns Promise<void>

Abstractdisconnect

• disconnect(session: string): Promise<void>

  Closes the IMAP connection.

  Always call this when done, preferably in a finally block.

  Parameters

  • session: string

    Session handle from connect()

  Returns Promise<void>

Abstractwatch

• watch(key: string, options: ImapWatchOptions, callback: Callback): Promise<void>

  Starts (or updates) a server-maintained IMAP IDLE push watch on a mailbox. The platform holds the connection open and invokes callback whenever the mailbox changes (new mail, flag changes), so the connector can run an incremental sync within seconds instead of waiting for its next poll.

  Idempotent upsert per key: re-calling with the same options while the watch is healthy is a cheap no-op, so connectors should re-arm the watch from their recurring poll — that both restarts a watch the platform may have dropped and refreshes rotated credentials. Calling with changed options reconnects with the new configuration.

  The callback is invoked with no additional arguments — bind what you need (e.g. the channel id) when creating it. Expect bursts: route the callback through scheduleDrain rather than syncing inline. Push can be lossy across reconnects (the platform catches up on reconnect, but keep a recurring poll as the outer safety net).

  Parameters

  • key: string

    Stable watch identity within this connector instance (e.g. the channel id). One live watch per key.

  • options: ImapWatchOptions

    Server, credentials, and mailbox to watch. The host must be in the declared hosts list.

  • callback: Callback

    Token from this.callback(...) to invoke on changes

  Returns Promise<void>

  Throws

  If the host is not in the declared hosts list

Abstractunwatch

• unwatch(key: string): Promise<void>

  Stops the push watch for key and discards its stored configuration. Call from onChannelDisabled (and any other teardown path). No-op if no watch exists.

  Parameters

  • key: string

    The key the watch was created with

  Returns Promise<void>

AbstractfetchAttachment

• fetchAttachment(
      session: string,
      uid: number,
      partNumber: string,
  ): Promise<Uint8Array<ArrayBufferLike>>

  Fetches the raw, decoded bytes of one MIME part of a message — typically an attachment discovered via fetchMessages()'s attachments field.

  Issues a separate FETCH for just that part (attachment bytes are not included by fetchMessages(), which only reports part metadata), and decodes the part's content per its own Content-Transfer-Encoding (base64 or quoted-printable) to raw bytes.

  Parameters

  • session: string

    Session handle from connect()

  • uid: number

    Message UID (from fetchMessages())

  • partNumber: string

    IMAP part number, e.g. attachments[i].partNumber from fetchMessages() (like "2" or "2.1")

  Returns Promise<Uint8Array<ArrayBufferLike>>

  The part's raw decoded bytes

  Throws

  If the message or part cannot be found, or the fetch fails

Static ReadonlyOptions