<!-- BusyBot node reference — https://busybot.net/tools/email-imap-trigger/ -->

> Node: Email Trigger (IMAP) (`email_imap_trigger`) · Polling trigger · v1
> Category: Communication · Credentials: IMAP (`imap`)
> Updated: 2026-08-16

# Email Trigger (IMAP)

> Trigger workflows when new emails arrive via IMAP

## Overview

The Email Trigger (IMAP) node polls an IMAP mail server at a configurable interval using a connect-check-disconnect cycle. On each poll it connects to the IMAP server, selects the configured mailbox (default INBOX), searches for messages with a UID greater than the last processed UID, fetches those messages, optionally marks them as read, disconnects, and returns the new emails as workflow items. On the very first poll the node establishes a baseline by recording the current highest message UID and returning no items, preventing a flood of historical emails. Supports three output formats: Simple (parsed headers and body text), Resolved (full MIME-parsed output with attachments extracted), and Raw (unprocessed message source).

**Category:** Communication  
**Tool Name:** `email_imap_trigger`  
**Version:** 1

**Appearance:** Icon: `lucide-MailOpen` | Color: `#6366f1`

## Node Type

**Trigger** — polling (checks for new data on a schedule)

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | None (trigger node) |
| Output | `Output` |

## Credentials

This tool requires **IMAP** credentials.
See the [Credentials Guide](https://busybot.net/credentials/imap/) for setup instructions.

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Mailbox Name | `string` | No | `INBOX` | The IMAP mailbox/folder to monitor for new emails. |
| Action | `options` | No | `read` | What to do after the email has been received. If "Nothing" is selected, emails will be processed again on subsequent polls unless custom search criteria exclude them. |
| | | | | Options: `read` (Mark as Read), `nothing` (leave the message untouched) |
| Format | `options` | No | `simple` | The format to return the email message in. |
| | | | | Options: `simple` (parsed headers and body text — best for most use cases), `resolved` (fully MIME-parsed email with attachments extracted), `raw` (the raw email source as a string, unparsed) |
| Download Attachments | `boolean` | No | `false` | Whether attachments of emails should be downloaded. Only set if needed as it increases processing. _(shown when Format is `simple`)_ |
| Property Prefix Name (`dataPropertyAttachmentsPrefixName`) | `string` | No | `attachment_` | Prefix for name of the attachment property. An index starting with 0 will be added. So if name is "attachment_" the first attachment is saved to "attachment_0". _(shown when Format is `resolved`)_ |
| Property Prefix Name (`dataPropertyAttachmentsPrefixNameSimple`) | `string` | No | `attachment_` | Prefix for name of the attachment property. An index starting with 0 will be added. So if name is "attachment_" the first attachment is saved to "attachment_0". _(shown when Format is `simple` and Download Attachments is `true`)_ |
| Options | `collection` | No | `{}` | Additional configuration options for email processing. |
| — Custom Email Rules | `string` | No | `["UNSEEN"]` | Custom IMAP search criteria as a JSON array. Examples: ["UNSEEN"], ["ALL"], ["UNSEEN", ["FROM", "boss@example.com"]], ["UNSEEN", ["SUBJECT", "invoice"]]. |
| — Fetch Only New Emails | `boolean` | No | `true` | Whether to fetch only new emails since the last run (using UID tracking), or all emails that match the search criteria on every poll. |
| Poll Interval | `number` | No | `1` | How often to check the mailbox for new emails. |
| Poll Interval Unit | `options` | No | `minutes` | Unit for the poll interval. |
| | | | | Options: `seconds`, `minutes`, `hours` |

## Output Data

Each new message becomes one output item. Every item carries `attributes.uid` (the IMAP UID of the message), `_trigger` (always `email_imap_polling`) and `_timestamp` (when the poll ran). The remaining shape depends on **Format**.

`simple` — headers from the message envelope plus the decoded body:

```json
{
  "textHtml": "<p>Invoice attached.</p>",
  "textPlain": "Invoice attached.",
  "from": "Billing <billing@example.com>",
  "to": "accounts@mycompany.com",
  "cc": "",
  "date": "2026-08-15T09:00:00.000Z",
  "subject": "Invoice 4192",
  "metadata": {
    "message-id": "<4192@example.com>",
    "in-reply-to": ""
  },
  "attributes": { "uid": 1042 },
  "_trigger": "email_imap_polling",
  "_timestamp": "2026-08-15T09:01:00.000Z"
}
```

With **Download Attachments** on, the item also gets `attachments` — one entry per file with `filename`, `contentType` and `size` — and one binary property per file, named with the configured prefix plus a zero-based index (`attachment_0`, `attachment_1`, …).

`resolved` — the fully MIME-parsed message: `from`, `to`, `cc`, `subject`, `date`, `html`, `text`, `textAsHtml`, `messageId`, `inReplyTo`, `references`, `headers` (every header line keyed by name) and `attributes.uid`. Attachments are always written to binary properties using the configured prefix and a zero-based index.

`raw` — `raw` (the unparsed message source as a string) and `attributes.uid`, nothing else.

Reference values downstream by expression, e.g. `{{ $json.subject }}`.

## Usage Examples

- Start a workflow when a new email arrives in your inbox
- Monitor a shared mailbox for incoming support requests
- Trigger automation when an email with a specific subject is received
- Process incoming invoices by email automatically

## Example Configuration

Watch INBOX for unread mail and mark each processed message as read:

```json
{
  "type": "email_imap_trigger",
  "parameters": {
    "mailbox": "INBOX",
    "postProcessAction": "read",
    "format": "simple",
    "pollInterval": 1,
    "pollIntervalUnit": "minutes",
    "options": {
      "customEmailConfig": "[\"UNSEEN\"]",
      "trackLastMessageId": true
    }
  }
}
```

Watch a folder and download attachments alongside the parsed body:

```json
{
  "type": "email_imap_trigger",
  "parameters": {
    "mailbox": "Important",
    "postProcessAction": "read",
    "format": "simple",
    "downloadAttachments": true,
    "dataPropertyAttachmentsPrefixNameSimple": "email_attachment_",
    "pollInterval": 1,
    "pollIntervalUnit": "minutes",
    "options": {
      "customEmailConfig": "[\"UNSEEN\"]",
      "trackLastMessageId": true
    }
  }
}
```

Fully parse each message and leave the mailbox untouched, filtered by subject:

```json
{
  "type": "email_imap_trigger",
  "parameters": {
    "mailbox": "INBOX",
    "postProcessAction": "nothing",
    "format": "resolved",
    "dataPropertyAttachmentsPrefixName": "file_",
    "pollInterval": 30,
    "pollIntervalUnit": "seconds",
    "options": {
      "customEmailConfig": "[\"UNSEEN\", [\"SUBJECT\", \"urgent\"]]",
      "trackLastMessageId": false
    }
  }
}
```

Hand the raw message source to a downstream node for custom parsing:

```json
{
  "type": "email_imap_trigger",
  "parameters": {
    "mailbox": "Processing",
    "postProcessAction": "read",
    "format": "raw",
    "pollInterval": 10,
    "pollIntervalUnit": "minutes",
    "options": {
      "customEmailConfig": "[\"ALL\"]",
      "trackLastMessageId": true
    }
  }
}
```

### Trigger Behavior

- **Activation:** Polling starts when the workflow is activated. There is no poll at the moment of activation — the first check runs one full interval later.
- **Schedule:** The trigger polls for new data based on the configured polling interval.
- **State:** Maintains internal state (the highest message UID processed so far) so each poll returns only messages that arrived since the last check.
- **First Run:** The first poll records the current highest UID and returns no items, so activating the workflow never replays the existing mailbox.
- **Testing:** Running the node from the editor emits a single sample email so you can build the rest of the workflow; real mail arrives only while the workflow is activated.

## Tips

Configure your IMAP server credentials (host, port, user, password). Select the mailbox to monitor (default: INBOX). Choose what to do with processed emails (mark as read or leave unchanged). The trigger connects to your mail server on each poll cycle, fetches new messages, and disconnects. On first activation it establishes a baseline and will only trigger on emails received afterward.

### Parameter Relationships

The attachment-related parameters have conditional dependencies:

1. **Simple format with attachments:**
   - Set `format` to `"simple"`
   - Set `downloadAttachments` to `true`
   - Optionally set `dataPropertyAttachmentsPrefixNameSimple`

2. **Resolved format (attachments included automatically):**
   - Set `format` to `"resolved"`
   - Optionally set `dataPropertyAttachmentsPrefixName`

3. **Raw format (no attachment processing):**
   - Set `format` to `"raw"`
   - No attachment parameters available

### Notes

- Turning **Fetch Only New Emails** off makes every poll return all messages matching the search criteria, so pair it with criteria that stop matching once a message is processed — for example `["UNSEEN"]` together with the `Mark as Read` action.
- A single poll returns at most 500 messages; anything beyond that is picked up on the following poll.