Creating Plot Twists
    Preparing search index...

    Class ImapAbstract

    Built-in tool for IMAP email access.

    Provides high-level IMAP operations for reading email and managing flags. Handles TCP/TLS connections, IMAP protocol details, and MIME decoding internally.

    Permission model: Connectors declare which IMAP hosts they need access to. Connections to undeclared hosts are rejected.

    class AppleMailConnector extends Connector<AppleMailConnector> {
      build(build: ConnectorBuilder) {
        return {
          options: build(Options, {
            email: { type: "text", label: "Apple ID Email", default: "" },
            password: { type: "text", label: "App-Specific Password", secure: true, default: "" },
          }),

          imap: build(Imap, { hosts: ["imap.mail.me.com"] }),
          integrations: build(Integrations),
        };
      }

      async syncInbox() {
        const session = await this.tools.imap.connect({
          host: "imap.mail.me.com",
          port: 993,
          tls: true,
          username: this.tools.options.email,
          password: this.tools.options.password,
        });

        try {
          await this.tools.imap.selectMailbox(session, "INBOX");
          const uids = await this.tools.imap.search(session, { unseen: true });
          const messages = await this.tools.imap.fetchMessages(session, uids, {
            body: true,
            bodyType: "html",
          });

          for (const msg of messages) {
            await this.tools.integrations.saveLink({
              source: `apple-mail:${msg.messageId}`,
              title: msg.subject ?? "(no subject)",
              // ...
            });
          }
        } finally {
          await this.tools.imap.disconnect(session);
        }
      }
    }

    Hierarchy (View Summary)

    Index

    Constructors

    constructor

    Methods

    connect listMailboxes selectMailbox search fetchMessages setFlags disconnect

    Properties

    Options

    Constructors

    Methods

    • Opens a connection to an IMAP server and authenticates.

      Parameters

      Returns Promise<string>

      An opaque session handle for subsequent operations

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

    • Lists all mailboxes (folders) on the server.

      Parameters

      • session: string

        Session handle from connect()

      Returns Promise<ImapMailbox[]>

      Array of mailbox descriptors

    • 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

    • 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

    • 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

    • 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>

    • Closes the IMAP connection.

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

      Parameters

      • session: string

        Session handle from connect()

      Returns Promise<void>

    Properties

    Options: { hosts: string[] }

    Type Declaration

    • hosts: string[]

      IMAP server hostnames this tool is allowed to connect to.

    Settings

    Member Visibility

    On This Page

    Constructors
    Methods
    Properties