All nodes/Integrations/Email

Fetch Emails

Fetches emails from a mailbox by criteria (UNSEEN, ALL, FROM ...). Returns a list of emails with headers and body. Connection: an Email connection node on the 'Email connection' port, or a saved connection picked in the node itself (the port wins).

Fetch Emails▶

Email connectionEmails

Error

Type in the graph: fetch_emails

Exec

An error output can be enabled to handle failures on their own path.

Try it

Minimal working scenario

Entry

Fetch Emails▶

Email Config

Exit▶

Execute
Data
Execute + Data

Press “Copy nodes”, open the editor and hit Ctrl+V on the canvas.

Pick your own connection or knowledge base first — the graph carries REPLACE_ME.

When to use it

This node reads a mailbox on a schedule or a webhook and hands the messages to the rest of the graph as data: tickets for a CRM, inbound requests, service notifications. You decide which messages are selected, not a model; when the agent should decide what to look for, attach the Email Tool to it instead.

How it works

“What to Fetch” builds the search expression for you: “Unread only”, “All messages”, “From a sender”, “Since a date”, and “Raw IMAP criteria” for whatever the first four do not cover. The field the chosen mode needs appears right below it.

The output is a list of emails (newest first), a total_fetched count and the mailbox name. Every message carries uid, subject, sender, recipients, date, body_text, body_html and is_read. The body comes from the message’s first text part; attachments are not downloaded, so their contents are not in the output.

All of that is IMAP. A POP3 connection has no folders, no server-side search and no flags: the node returns the newest messages, “Mailbox”, “What to Fetch” and “Mark as Read” have no effect, and mailbox comes back empty.

Common mistakes

“Unread only” with “Mark as Read” turned off. The mailbox is then opened read-only and nothing ever marks the messages read — every run brings back the very same ones.
Expecting a rollback. With the flag on, messages are marked read as they are fetched, even if the next node fails. They will not arrive a second time.
Treating uid as a permanent key. It is the message’s position in the folder at fetch time, not a stable identifier: delete a message and the numbers shift. For deduplication across runs prefer the subject plus date, or a marker you write yourself.
More than a hundred messages at once. “Max emails” is capped at 100; the rest needs another run or a narrower selection.
A free-form date. “Since Date” accepts 2026-07-01 or 01-Jul-2026; anything else is an error.

Inputs

Port	Wire	Payload	Notes
Email connection`email_config`	Data`data`	—	required

Outputs

Port	Wire	Payload	Notes
Emails`output`	Execute + Data`execute_data`	`object`
Error`on_error`	Execute + Data`execute_data`	—	shown when expose_error_output = true

Configuration

Field	Type	Default	Description
Email connection`connection_id`	`string`	`""`	Saved workspace email connection, so a simple graph does not need a separate Email Config node. A node wired to the 'email_config' port wins over this field. connection: emailoverridden by port: email_config
Mailbox`mailbox`	`string`	`INBOX`	Mailbox/folder to fetch from. IMAP only — POP3 has no folders and always reads the inbox.
Max emails`max_count`	`integer`	`10`	How many messages to fetch at most, newest first.
What to Fetch`criteria_mode`	`string`	`unseen`	Which messages to select. IMAP only — POP3 always returns the newest messages. Options: `unseen` — Unread only, `all` — All messages, `from` — From a sender, `since` — Since a date, `raw` — Raw IMAP criteria
Sender`criteria_from`	`string`	`""`	Match messages whose From contains this address shown when «What to Fetch» = From a sender
Since Date`criteria_since`	`string`	`""`	Match messages delivered on or after this date (YYYY-MM-DD or DD-Mon-YYYY) shown when «What to Fetch» = Since a date
Raw IMAP Criteria`search_criteria`	`string`	`UNSEEN`	Raw IMAP SEARCH expression, e.g. UNSEEN, ALL, FROM user@example.com shown when «What to Fetch» = Raw IMAP criteria
Mark as Read`mark_as_read`	`boolean`	`true`	Set the \Seen flag on fetched messages. Turning this off with 'Unread only' re-delivers the same messages on every run forever — the mailbox is opened read-only, so nothing ever marks them read. IMAP only.

Shared fields

Every node has these three — the platform adds them, not the node author.

expose_error_output — When enabled, show an execution output to connect nodes that run if this step fails.