readConnectorEmails

Reads historical email from an existing IMAP connector without advancing connector checkpoints, ingesting messages, or marking messages read. Use this when a workflow needs mailbox analysis rather than background event ingestion.

Connector behavior

• The selected connector must be enabled.
• Background polling may be off; workflows can still read the mailbox.
• Password and OAuth2 / XOAUTH2 IMAP connectors are supported. OAuth2 connectors refresh their access token before connecting when refresh credentials are present.
• Results include headers, body excerpts, message IDs, dates, and attachment metadata, not parsed attachment text.

Usage

import type { Id } from "@/convex/_generated/dataModel";
import { readConnectorEmails } from "@/workflows/shared/actions/imap";

const { emails } = await readConnectorEmails({
  record,
  stepKey: "mailboxHistory",
  connectorId: record.input.connectorId as Id<"connectors">,
  sinceDays: 180,
  limit: 200,
});