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 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:

{
  "_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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

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

Compound search criteria — unread invoices only:

{
  "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:

{
  "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.