IMAP Trigger Node — BizFirstAI

What this node does: The IMAP Trigger polls a mailbox on a configured schedule using the IMAP protocol (RFC 3501). For each email that matches the search criteria and has not been processed before, it fires a workflow execution with the email data as the trigger payload. UID tracking prevents duplicate processing across poll cycles.

Polling Model

Schedule fires — The BizFirstAI scheduler invokes the IMAP Trigger node on its configured interval.

Connect to IMAP server — Opens a TLS (or plain) connection to the configured Host:Port using the provided credentials. Connection, authentication, and command timeouts are all configurable.

Search mailbox — Executes the RFC 3501 search criteria (CustomEmailConfig) against the specified Mailbox folder (default: INBOX).

UID deduplication — Compares results against the LastSeenUid stored in distributed cache. Only emails with UIDs greater than the last seen value are processed.

Fire workflow executions — One execution fires per new email, up to BatchSize (default 20) per poll. Output format (simple, resolved, or raw) is applied at this stage.

Post-process action — After firing, apply PostProcessAction: mark as read (default), delete from server, or take no action.

Update state — Saves the new LastSeenUid and poll metadata to distributed cache. Disconnects from the IMAP server cleanly.

UID Deduplication

The IMAP Trigger uses IMAP UIDs (Unique Identifiers) to track which emails have already been processed. State is persisted in the distributed cache under the key:

imap_trigger_state:{workflowId}:{nodeId}

The cache stores the following fields:

State Field	Description
`LastSeenUid`	The highest UID processed in the previous poll. New emails with UIDs strictly greater than this value will be processed.
`ActivatedAt`	Timestamp when the trigger was first activated. Used for initial boundary computation.
`LastPollCompletedAt`	Timestamp of the last completed poll cycle.
`TotalEmailsProcessed`	Running count of total emails processed by this trigger across all poll cycles.

DownloadEmailOnEveryTrigger warning: Setting DownloadEmailOnEveryTrigger: true disables UID tracking entirely. Every poll cycle will re-process all emails matching the search criteria, regardless of whether they have been seen before. This will cause duplicate workflow executions. Only use this setting for development and debugging purposes.

Output Formats

Format	Description
`simple`	Default. Returns a parsed JSON object with common fields: `from`, `to`, `subject`, `date`, `text`, `html`, and an `attachments` array. Attachment download is only available in this format. Most suitable for standard email-processing workflows.
`resolved`	Fully structured output with `ImapAddressInfo` objects for all address fields. Each address entry contains separate `Name` and `Address` properties. Use when precise sender/recipient parsing is required.
`raw`	Returns the complete RFC 822 email as base64-encoded bytes. Use for archival, compliance forwarding, or when a downstream node requires the raw MIME message for its own parsing.

Comparison with Gmail Trigger

Capability	IMAP Trigger	Gmail Trigger
Authentication	Username + Password (direct IMAP)	OAuth2 via CredentialId (Google only)
Compatible mailboxes	Any IMAP server (Gmail, Outlook, Exchange, custom)	Gmail only
Search filter syntax	RFC 3501 IMAP search criteria (JSON array)	Gmail query string syntax
Deduplication mechanism	IMAP UID tracking in distributed cache	Gmail API — filters by last poll timestamp
Output formats	simple / resolved / raw	Simplified on/off
Attachment download	simple format only	All operations
Post-process action	mark read / delete / nothing	MarkAsRead flag
Label management	Not available — IMAP folders only	Full label CRUD
Batch size control	BatchSize 1–100	MaxEmailsPerPoll

In This Guide

Configuration

Full property reference: connection settings, search criteria, output format, post-process action, and all timeout parameters.

Input & Output

All three output format schemas — simple, resolved, and raw — with attachment object detail and downstream field reference patterns.

Examples

Five examples: basic unread trigger, filter by sender and date, process attachments, delete after processing, and combine with CodeExecute to parse a CSV attachment.

Security note: IMAP credentials (username and password) are stored in the workflow configuration. Use BizFirst's encrypted secrets store for production deployments. Only enable AllowUnauthorizedCerts: true in development environments — never in production.