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

> Node: Email Read (IMAP) (`email_read_imap`) · Action (binary) · v1
> Category: Communication · Credentials: IMAP (`imap`)
> Updated: 2026-08-16

# Email Read (IMAP)

> Fetch emails from IMAP server and download attachments

## Overview

The Email Read IMAP tool connects to an IMAP email server using provided credentials, fetches messages matching configurable search criteria (UNSEEN, ALL, FLAGGED, custom rules), and outputs one item per email with parsed metadata (from, to, subject, date, body). Supports three output formats: simple (structured fields), resolved (full parsed message), and raw (unprocessed body text). When download attachments is enabled (or format is resolved), email attachments are saved as separate binary properties (attachment_0, attachment_1, etc.).

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

**Appearance:** Icon: `lucide-MailOpen` | Color: `#44AA22`

## Node Type

**Action (Binary)** — handles file/binary data operations

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | `Input` |
| Output | `Output`, `Error` |

## 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 | `string` | No | `INBOX` | The IMAP mailbox/folder to read emails from (e.g., INBOX, Sent, Drafts, or a custom folder). Supports expressions. |
| Format | `options` | No | `simple` | The format to return email messages in. |
| | | | | Options: `simple` (structured output with parsed text, headers, and optional attachments), `resolved` (full email parsed with all data resolved and attachments always saved as binary data), `raw` (raw email body text without parsing — no attachments) |
| Search Criteria | `string` | No | `["UNSEEN"]` | IMAP search criteria as a JSON array. Examples: ["UNSEEN"], ["ALL"], [["FROM","user@example.com"]], [["SUBJECT","invoice"], "UNSEEN"], [["SINCE","01-Jan-2025"]]. Multiple criteria are ANDed together. Supports expressions. |
| Download Attachments | `boolean` | No | `false` | Whether to download email attachments as binary data. Only applies when Format is Simple. Resolved format always downloads attachments. _(shown when Format is `simple`)_ |
| Attachment Property Prefix (`binaryPropertyName`) | `string` | No | `attachment_` | Prefix for binary property names of downloaded attachments. An index starting at 0 is appended (e.g., attachment_0, attachment_1). Names are case-sensitive. _(shown when Format is `resolved`)_ |
| Attachment Property Prefix (`binaryPropertyName`) | `string` | No | `attachment_` | Prefix for binary property names of downloaded attachments. An index starting at 0 is appended (e.g., attachment_0, attachment_1). Names are case-sensitive. _(shown when Format is `simple` and Download Attachments is `true`)_ |
| Mark as Read | `boolean` | No | `true` | Whether to mark fetched emails as read (add \Seen flag) after processing. |
| Limit | `number` | No | `50` | Maximum number of emails to fetch per input item. Set to 0 for unlimited. |
| Max Concurrency | `number` | No | `1` | Maximum number of input items to process concurrently. Keep low since each item opens an IMAP connection. |

## Output Data

Each input item triggers one mailbox fetch and **fans out to one output item per email found**. The email replaces the item JSON — upstream fields are not merged in — and every output item carries a `_emailReadImap` property describing its position in the fetch:

```json
{
  "_emailReadImap": {
    "emailIndex": 0,
    "emailCount": 12,
    "mailbox": "INBOX"
  }
}
```

When no email matches the search criteria, the input item passes through unchanged with `_emailReadImap` set to `{ "emailCount": 0, "mailbox": "INBOX" }`, so an empty mailbox never silently drops the branch.

The rest of the JSON depends on **Format**:

| Format | Fields on the output item |
|--------|---------------------------|
| `simple` | `from`, `to`, `cc`, `date`, `subject`, `textPlain`, `textHtml`, `metadata` (every header other than from/to/cc/date/subject), `attributes.uid` |
| `resolved` | `from`, `to`, `cc`, `bcc`, `subject`, `date` (ISO 8601), `messageId`, `inReplyTo`, `references`, `html`, `text`, `textAsHtml`, `headers` (all header lines keyed by name), `attributes.uid` |
| `raw` | `raw` (the unparsed message source) and `uid` |

Attachments are written as binary properties named with the **Attachment Property Prefix** plus a zero-based index — `attachment_0`, `attachment_1`, and so on — each keeping the original file name and MIME type. Binary data arriving on the input item is merged through alongside them. `resolved` always downloads attachments; `simple` only does so when **Download Attachments** is on; `raw` never does.

Reference an email downstream by expression, e.g. `{{ $json.subject }}` or `{{ $json._emailReadImap.emailCount }}`.

## Usage Examples

- Read unread emails from INBOX
- Fetch emails from a specific sender
- Download email attachments as binary data
- Read all flagged emails from a custom folder
- Get emails with subject containing "invoice"

## Example Configuration

Fetch unread emails and mark them read:

```json
{
  "type": "email_read_imap",
  "parameters": {
    "mailbox": "INBOX",
    "format": "simple",
    "searchCriteria": "[\"UNSEEN\"]",
    "markAsRead": true,
    "limit": 50
  }
}
```

Fetch all emails from a specific sender without changing their read state:

```json
{
  "type": "email_read_imap",
  "parameters": {
    "mailbox": "INBOX",
    "format": "simple",
    "searchCriteria": "[[\"FROM\",\"sender@example.com\"]]",
    "markAsRead": false,
    "limit": 10
  }
}
```

Simple format with attachment download under a custom prefix:

```json
{
  "type": "email_read_imap",
  "parameters": {
    "mailbox": "INBOX",
    "format": "simple",
    "searchCriteria": "[\"UNSEEN\"]",
    "downloadAttachments": true,
    "binaryPropertyName": "email_attachment",
    "markAsRead": true,
    "limit": 25
  }
}
```

Resolved format, which parses the whole message and always saves attachments:

```json
{
  "type": "email_read_imap",
  "parameters": {
    "mailbox": "INBOX",
    "format": "resolved",
    "searchCriteria": "[\"ALL\"]",
    "binaryPropertyName": "attachment",
    "markAsRead": true,
    "limit": 100
  }
}
```

Raw format for downstream text processing, reading a non-default folder with no limit:

```json
{
  "type": "email_read_imap",
  "parameters": {
    "mailbox": "Sent",
    "format": "raw",
    "searchCriteria": "[[\"SINCE\",\"01-Jan-2025\"]]",
    "markAsRead": false,
    "limit": 0
  }
}
```

Compound search criteria — unread invoices only:

```json
{
  "type": "email_read_imap",
  "parameters": {
    "mailbox": "INBOX",
    "format": "simple",
    "searchCriteria": "[[\"SUBJECT\",\"invoice\"], \"UNSEEN\"]",
    "downloadAttachments": true,
    "binaryPropertyName": "invoice_attachment",
    "markAsRead": true,
    "limit": 20
  }
}
```

Historical search combining a sender and a date range:

```json
{
  "type": "email_read_imap",
  "parameters": {
    "mailbox": "INBOX",
    "format": "simple",
    "searchCriteria": "[[\"FROM\",\"reports@company.com\"], [\"SINCE\",\"01-Dec-2024\"]]",
    "markAsRead": false,
    "limit": 0
  }
}
```

### Error Handling

| Mode | Behavior |
|------|----------|
| **stop** | Halts workflow on first error |
| **continue** | Skips failed items, passes successful ones through |
| **errorPort** | Routes failed items to Error output port |

## Tips

Connect to an IMAP email server, fetch messages matching search criteria, and download attachments as binary data.

### Choosing a format

- **`simple`** gives you the fields most workflows need — sender, recipients, subject, date, plain-text and HTML bodies — with attachments optional. Start here.
- **`resolved`** parses the entire message, including `bcc`, `messageId`, `inReplyTo`, `references` and every header line, and always downloads attachments. Use it for threading, auditing, or when you need a header the simple format folds into `metadata`.
- **`raw`** returns the message source untouched and never downloads attachments. Use it for custom parsing or text analysis.

### Notes

- **Search criteria must be valid JSON.** Wrap the array in a string, escaping the inner quotes — `"[\"UNSEEN\"]"`. Multiple criteria are ANDed together; each nested array is a key/value pair such as `["FROM","user@example.com"]`.
- **Mark as Read runs after the fetch.** With it on, the same emails are not returned by a later `["UNSEEN"]` run — that is what makes an unread-mailbox poll idempotent. Turn it off when you only want to inspect a mailbox.
- **One node run can produce many items.** Set **Limit** to bound the fan-out, or `0` to take everything matching.
- **Keep Max Concurrency low.** Each input item opens its own IMAP connection, and most mail servers cap simultaneous connections per account.
- **Attachment property names are case-sensitive.** Downstream nodes must reference them exactly as `{prefix}{index}` — check the node's Binary Data panel for the names produced by a run.
- This node reads a mailbox on demand as part of a running workflow. To *start* a workflow when mail arrives, use the Email Trigger (IMAP) node instead.