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. Each new email that meets your configuration filters will trigger one separate workflow run containing the email's details. The system tracks processed emails by their IMAP UID to prevent duplicate runs.

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
`includeAttachments`	switch	No	`false`	Whether to download attachments immediately during the trigger
`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,
    "attachments": [] 
  },
  "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:

Leave Include Attachments disabled on the trigger to keep payload sizes small.
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.