IMAP connector

The IMAP connector polls an email mailbox, applies ingestion filters, stores normalized emails in Convex, and emits email.received events. It is transport infrastructure for inbound mail and optional SMTP replies; workflow routing lives in Triggers.

Configuration

IMAP connector configuration is normalized through one shared module. The same rules apply when a connector is created, edited, tested, redacted for the UI, loaded by workflows, or loaded by connector-runtime.

• Name, enabled flag, background polling flag, host, port, username, authentication mode, and TLS.
• Authentication modes: password or OAuth2 / XOAUTH2. OAuth2 supports browser Google consent, a stored access token, or a refresh token with token URL and scope.
• Mailbox, unread-only filtering, lastDays lookback, and poll interval.
• Optional SMTP settings for replies: SMTP host, port, TLS, username, password, and from address.
• Optional reply instructions copied into workflow event context for reply drafting.
• Ingestion filters with fromContains, subjectContains, hasAttachments, and enabled.

Google Workspace OAuth2

For Google Workspace Gmail, use OAuth2 / XOAUTH2 instead of mailbox password authentication. Configure the IMAP host as imap.gmail.com, port 993, TLS enabled, and the full mailbox address as username.

• Configure GOOGLE_WORKSPACE_OAUTH_CLIENT_ID and GOOGLE_WORKSPACE_OAUTH_CLIENT_SECRET in the web app and connector-runtime environments.
• The OAuth redirect URI is /api/connectors/google/callback. Set GOOGLE_WORKSPACE_OAUTH_REDIRECT_URI only if Google Cloud must use a different absolute callback URL.
• Token URL defaults to https://oauth2.googleapis.com/token.
• Scope defaults to https://mail.google.com/.
• In the connector form, select OAuth2 / XOAUTH2 and use Connect Google to consent as the mailbox user. Flowman stores the returned refresh token and refreshes access tokens before connecting.
• If SMTP is configured on an OAuth2 connector and no SMTP password is set, replies use the same OAuth2 credentials.

Workflow context

Use reply instructions to store mailbox-specific guidance for workflows that draft or send replies. When the connector emits an email.received event, Flowman copies the value to event.email.replyInstructions and event.replyInstructions. Workflows can pass that context into aiInvoke or other actions without requiring each workflow run to provide manual instructions.

SMTP replies

SMTP settings are required only when a workflow uses replyToEmail. The action sends through the same connector that received the triggering email, so replies use the same mailbox identity and preserve the original conversation.

• If SMTP username or password is blank, Flowman falls back to the IMAP username or password.
• From address is optional; when omitted, replies use the SMTP username.
• Existing connectors can keep ingesting without SMTP configured, butreplyToEmail fails clearly until SMTP settings are added.
• Outbound reply metadata is stored in outboundEmails, including recipients, subject, delivery status, thread headers, and timestamps.

Ingestion filters

Filters decide whether an email should be stored. They do not decide which workflow should run.

• If no filters are configured, every polled email is eligible for ingestion.
• Multiple filters are OR'd: an email matches if any enabled filter matches every configured field.
• hasAttachments only filters when enabled on a rule.
• Matching emails are inserted idempotently by connector and UID.

Polling behavior

enabled means the connector can be selected by workflows. pollingEnabled controls whether connector-runtime polls and ingests mail in the background. Turn polling off for analysis-only connectors.

• Normal polling fetches messages newer than the connector checkpoint.
• Unread-only connectors scan unread messages in the configured lookback window, even if a message UID is already at the connector checkpoint.
• Resetting a connector checkpoint sets the worker UID back to 0 and enqueues a runtime sync signal. Connector-runtime reloads the checkpoint and wakes the worker for an immediate mailbox poll.

Coding-agent requests

Matching emails can carry coding-agent request controls. The connector strips recognized control lines from the prompt and exposes them on the event payload for trigger mappings.

Repo: flowman-web
Plan-Mode: false

Implement the attached task notes.

• Repository controls support Repo:, Repository:, and subject tags such as [repo:flowman-web].
• Plan mode controls support Plan-Mode: true, Plan-Mode: false, mode: plan, mode: direct, and subject tags such as [direct].
• Supported email attachments are uploaded to Convex File Storage before the event is ingested, then exposed as email.workflowAttachments. Images, PDFs, and text files are accepted up to 20 MB each.
• If a supported attachment cannot be stored, the email is not ingested and the workflow is not triggered without the expected file.

Stored records

• emails: normalized matching email records with sender, recipients, subject, body, attachment metadata, UID, thread headers, and matched ingestion filter indexes.
• events: emitted after a new email is stored, with sourceType: "connector" and type: "email.received".
• Connector reply instructions are included in the event payload when configured, not copied onto the stored email record.
• triggerDeliveries: created later by matching triggers, not by the connector itself.
• outboundEmails: populated by workflow actions that send replies through this connector.

Email maintenance

Connector detail shows recent ingested emails. Deleting an email from this table also deletes its linked events and triggerDeliveries, preventing orphaned routing records.