n8n - 💡(How to fix) Fix emailReadImap: add UID deduplication, batch size cap, and numeric uid enforcement

Summary

Three improvements to n8n-nodes-base.emailReadImap discovered while building an email triage workflow for LLM agents:

1. UID-based deduplication

Problem: The current "unseen" filter re-fetches emails that were marked unread after already being processed. In a polling workflow this causes the same email to be processed multiple times.

Proposed fix: Track lastMessageUid in workflow static data and only fetch emails with a UID greater than the last seen UID. This gives each run a stable watermark regardless of read/unread state.

const staticData = $getWorkflowStaticData('node');
const lastUid = staticData.lastMessageUid ?? 0;
// fetch only UIDs > lastUid
// after processing: staticData.lastMessageUid = maxUid;

2. Batch size cap

Problem: On large inboxes a single polling execution fetches hundreds of emails, creating very large payloads and often timing out.

Proposed fix: Add an optional batchSize parameter (default 20) that limits the number of emails returned per execution. Polling workflows can rely on the watermark (above) to catch up over multiple runs.

3. Numeric uid enforcement

Problem: The uid field on returned email items is typed as string in some code paths but IMAP UIDs are always integers. When used as a tool in an LLM-driven workflow, language models pass UUID strings (e.g. "3f2a1b...") instead of IMAP UIDs (e.g. 12345) because the type is ambiguous.

Proposed fix: Coerce attributes.uid to Number before returning and document it explicitly as an integer in the node's output schema.

Context

These were identified while building an email triage agent on top of n8n. We implemented them in a custom fork node (emailReadImapProsponsive) and all three have been running in production since February 2026 without issues.

Happy to contribute a PR if the approach looks good to maintainers.