IMAP Trigger

What it does

Starts a workflow when a new unseen email is found in the configured IMAP mailbox. The scheduler polls at a configurable interval; each new email fires one workflow run.

Inputs / config

• No runtime inputs.
• Config fields:
  • credentials_id (required): IMAP credential id (host, port, username, password, TLS).
  • mailbox (optional, default Inbox): mailbox folder to poll. Use the exact folder name as seen by your IMAP server (e.g. Inbox, INBOX, Sent, custom-folder).
  • poll_interval_seconds (optional, default 30, minimum 10): how often to poll for new emails.
  • mark_as_seen (optional, default true): mark processed emails as \Seen after the workflow fires.

Outputs

Field	Type	Description
triggered_at	string (RFC3339)	UTC time when the email triggered the run
trigger	string	Always imap_trigger
subject	string	Email subject line
from	string	Sender address (e.g. Name <[email protected]>)
to	string	First recipient address
date	string (RFC3339)	Date header from the email
body_text	string	Plain-text body
body_html	string	HTML body (empty string if not present)
uid	integer	IMAP UID of the message
mailbox	string	Mailbox the email was fetched from
run_id	string	Unique run identifier (imap:{proxyID}:{nodeID}:{uidvalidity}:{uid})

Referencing outputs

Use {{ $json['<node_id>'].field }} in downstream node inputs:

{{ $json['imap_trigger_1'].subject }}
{{ $json['imap_trigger_1'].from }}
{{ $json['imap_trigger_1'].body_text }}
{{ $json['imap_trigger_1'].uid }}

Credential setup

Create a credential of type IMAP in Settings → Credentials. Required fields:

Field	Description
Host	IMAP server hostname (e.g. imap.gmail.com)
Port	IMAP port (993 for TLS, 143 for STARTTLS)
Username	IMAP login username
Password	IMAP login password (encrypted at rest)
Use TLS	Check for direct TLS (port 993)

Multi-pod behaviour

In a multi-pod deployment, only one pod polls the mailbox at a time. A Redis ownership lock (imap_owner_lock:{proxyID}:{nodeID}) is acquired on startup and held via a heartbeat goroutine. Other pods wait and retry. If the owning pod dies, the lock expires and another pod takes over (within one lock TTL, which is max(60s, poll_interval × 3)).

Per-message UID deduplication (imap_uid_seen:…, TTL 7 days) ensures at-most-once processing even during failover handoffs.

Semantics

• At-most-once: a UID is claimed in Redis before the email body is fetched. If the workflow fails after claiming but before completing, the email is not retried (avoids duplicate downstream side effects).
• mark_as_seen: marking occurs after the workflow fires and is best-effort. If it fails, the UID deduplication key prevents a duplicate run on the next poll.

Testing with "Listen for Email"

Before enabling the workflow in production, use the Listen for Email test mode in the builder:

1. Select the IMAP Trigger node and open its config panel.
2. Click Listen for Email (or the trigger test button in the toolbar).
3. The builder connects read-only to your IMAP mailbox and waits for the first unseen email.
4. Send a test email to the configured account (or use an existing unseen email).
5. The captured email payload streams into the builder and the downstream workflow executes automatically.
6. Inspect each node's output to validate expressions and logic.

Note: Listen for Email works on both enabled and disabled workflows. You do not need to enable the workflow to run a test.

Production vs. test mode

Mode	Trigger condition	Workflow must be enabled?
Production scheduler	Polls at poll_interval_seconds; fires on every new unseen email	Yes
Listen for Email (test)	Fires once on the first unseen email found	No
Execute Workflow (test)	Runs with pinned/mock data	No

Starter template

The IMAP Email Echo template (imap_trigger_echo) connects an IMAP trigger to a code node that logs the email's subject, sender, UID, and a 200-character body preview to the run output.