IMAP Trigger

Trigger a workflow run automatically whenever a new email matches your criteria on an IMAP server.

The IMAP Email Trigger is a polling-based trigger that automatically monitors a designated mailbox (such as Gmail, Outlook, or Yahoo) at regular intervals.

graph TD
  A[IMAP Server / Mailbox] -->|New Email matches filters| B[Mandala Poller]
  B -->|Every 1 min| C[Trigger Workflow Run]

[!NOTE] Polling runs every 1 minute and fetches only the single newest matching email per poll (a backlog drains one email per minute, newest first). There's no UID or timestamp-based dedup -- avoiding duplicate runs depends entirely on filterUnreadOnly + markAsRead together; with both off, the same latest email can trigger repeatedly.

Configuration Inputs

Parameter	Type	Required	Default	Description
`imapHost`	string	Yes	-	IMAP server hostname (e.g. `imap.gmail.com`)
`imapPort`	string	Yes	`993`	IMAP server port
`imapSecure`	dropdown	Yes	`SSL`	Security protocol: `SSL`, `TLS`, or `None`
`imapUsername`	string	Yes	-	Your email address (e.g. `user@gmail.com`)
`imapPassword`	string	Yes	-	Password or App Password (recommended)
`mailbox`	string	No	`INBOX`	Mailbox folder to poll
`filterUnreadOnly`	switch	No	`true`	When active, only processes unread emails
`markAsRead`	switch	No	`false`	Marks processed emails as `SEEN` on the server
`filterFrom`	string	No	-	Filter by specific sender (e.g. `invoices@company.com`)
`filterSubject`	string	No	-	Filter emails by keyword in the subject

Outputs

When the trigger fires, the following payload structure is made available to subsequent blocks under the trigger object:

{
  "email": {
    "id": "12345", 
    "subject": "Invoice for June",
    "from": "billing@company.com",
    "to": "you@domain.com",
    "cc": "finance@domain.com",
    "date": "2026-06-16T10:15:30.000Z",
    "bodyText": "Hi there, please find attached...",
    "bodyHtml": "<p>Hi there, please find attached...</p>",
    "hasAttachments": true
  },
  "timestamp": "2026-06-16T10:16:00.000Z"
}

Downstream Integration (Attachments)

If you need to process email attachments (e.g. parse PDFs, extract tables, etc.), it is recommended to:

Use the hasAttachments output to decide whether to continue -- the trigger itself never downloads attachment content.
Chain the IMAP: Get Attachments block downstream.
Wire the message identifier field using:
```
{{trigger.email.id}}
```

Mail Provider Setup Instructions

Connecting to third-party mail providers usually requires configuring security rules:

Gmail Setup

Enable IMAP Access in your Gmail settings under Forwarding and POP/IMAP.
Turn on 2-Step Verification for your Google account.
Generate an App Password under Account Security, and use it as your imapPassword in Mandala.

Outlook / Office 365 Setup

Host: outlook.office365.com (Port 993, SSL).
Use an App Password if Multi-Factor Authentication is active on your tenant.