feat(imap): added support for imap trigger

[waleedlatif1]

Summary

• added support for imap trigger

fixes #2660

Type of Change

• Feature

Testing

Tested manually

Checklist

• Code follows project style guidelines
• Self-reviewed my changes
• Tests added/updated and passing
• No new warnings introduced
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Review	Updated (UTC)
docs	Skipped		Jan 2, 2026 11:16pm

[greptile-apps]

Greptile Summary

Adds IMAP trigger support enabling workflows to start when new emails arrive via IMAP protocol (Gmail, Outlook, Yahoo, etc.). Implements polling service with multi-mailbox monitoring, configurable search criteria, attachment handling, and proper concurrency control.

Key changes:

• Created imap-polling-service.ts with email fetching, filtering, and webhook triggering
• Added IMAP trigger configuration with dynamic mailbox selection and AI-powered search criteria builder
• Implemented /api/tools/imap/mailboxes endpoint for fetching available mailboxes
• Added /api/webhooks/poll/imap cron endpoint with distributed locking
• Registered IMAP trigger and block in respective registries
• Added cron job to Helm config (runs every 1 minute)
• Updated workflow comparison logic to exclude SYSTEM_SUBBLOCK_IDS from change detection
• Enhanced Gmail trigger with AI-powered search query builder (wandConfig)

Implementation highlights:

• Per-mailbox UID tracking prevents duplicate processing across folders
• 24-hour lookback on first poll prevents overwhelming initial run
• Concurrency control (max 5 webhooks in parallel) with proper self-removal pattern
• Time-based filtering with 1-minute buffer reduces redundant searches
• Manual MIME parsing for body text/HTML and attachments
• Session-authenticated mailbox endpoint prevents credential theft

Confidence Score: 4/5

• Safe to merge with minor issues already addressed in PR comments
• Solid implementation with proper authentication, error handling, and distributed locking. Previous review identified several issues (search criteria parsing, descending sort, Promise.race pattern, empty webhook secret) that the developer has acknowledged and addressed or confirmed as intentional. The core logic is sound with appropriate safeguards (idempotency, concurrency control, 24-hour first-poll window, per-mailbox UID tracking).
• Pay attention to apps/sim/lib/webhooks/imap-polling-service.ts - ensure previously noted issues were properly addressed

Important Files Changed

Filename	Overview
apps/sim/lib/webhooks/imap-polling-service.ts	Core IMAP polling service with email fetching, filtering, and webhook triggering logic; several issues already noted in previous threads
apps/sim/triggers/imap/poller.ts	IMAP trigger configuration defining UI subblocks, server settings, and authentication with proper fetchOptions implementation
apps/sim/app/api/tools/imap/mailboxes/route.ts	API endpoint for fetching IMAP mailboxes with session authentication and comprehensive error handling
apps/sim/app/api/webhooks/poll/imap/route.ts	Cron endpoint for IMAP polling with proper auth verification, distributed locking, and error handling

Sequence Diagram

sequenceDiagram
    participant Cron as Cron Job
    participant API as /api/webhooks/poll/imap
    participant Redis as Redis Lock
    participant Service as ImapPollingService
    participant IMAP as IMAP Server
    participant DB as Database
    participant Webhook as /api/webhooks/trigger

    Cron->>API: GET (every 1 minute)
    API->>API: Verify cron auth
    API->>Redis: Acquire lock (180s TTL)
    alt Lock acquired
        API->>Service: pollImapWebhooks()
        Service->>DB: Fetch active webhooks
        
        loop For each webhook (concurrency: 5)
            Service->>IMAP: Connect & authenticate
            
            loop For each mailbox
                Service->>IMAP: Search emails (criteria + UID filter)
                IMAP-->>Service: UIDs matching criteria
                Service->>IMAP: Fetch email data (envelope, body, attachments)
                IMAP-->>Service: Email content
                
                loop For each email
                    Service->>Service: Check idempotency
                    Service->>Webhook: POST email payload
                    Webhook-->>Service: Response
                    alt markAsRead enabled
                        Service->>IMAP: Add \Seen flag
                    end
                end
            end
            
            Service->>IMAP: Logout
            Service->>DB: Update lastProcessedUidByMailbox
            Service->>DB: Update webhook success/failure count
        end
        
        Service-->>API: Poll results
        API->>Redis: Release lock
        API-->>Cron: Success response
    else Lock not acquired
        API-->>Cron: 202 Skipped (polling in progress)
    end

Loading

[greptile-apps]

_{16 files reviewed, 3 comments}

_{Edit Code Review Agent Settings | Greptile}

[waleedlatif1]

@greptile

[greptile-apps]

_{19 files reviewed, 5 comments}

_{Edit Code Review Agent Settings | Greptile}

[waleedlatif1]

@greptile