IMAP - new-email source bug fix

[michelle0927]

Resolves #18604

Summary by CodeRabbit

• Bug Fixes

  • Improved new email detection to reduce false positives.
  • Prevents unnecessary historical processing when a mailbox has no messages, improving reliability and performance.

• Chores

  • Bumped component version to 0.0.6.
  • Upgraded platform dependency to the latest major version.
  • Added a small utility dependency to support internal operations.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

2 Skipped Deployments

Project	Deployment	Preview	Comments	Updated (UTC)
pipedream-docs	Ignored			Oct 2, 2025 4:38pm
pipedream-docs-redirect-do-not-edit	Ignored			Oct 2, 2025 4:38pm

[coderabbitai]

Walkthrough

Updates the IMAP component version and dependencies. Adjusts the New Email source logic to gate staleness checks and historical message processing behind a truthy mailbox message count. No exported API signatures changed beyond the version field.

Changes

Cohort / File(s)	Summary
IMAP package manifest components/imap/package.json	Version 0.0.5 → 0.0.6. Updates @pipedream/platform to ^3.1.0. Adds dependency util ^0.12.4.
IMAP New Email source logic components/imap/sources/new-email/new-email.mjs	Source version 0.0.5 → 0.0.6. hasNewMessages(box) now checks box.messages.total && before staleness logic. getHistoricalEvents() now performs fetch/processing only when box.messages.total is truthy.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  actor User as Workflow Runtime
  participant Src as IMAP New Email Source
  participant IMAP as IMAP Server

  User->>Src: Run source
  Src->>IMAP: Connect and open mailbox
  IMAP-->>Src: box (incl. messages.total, uidnext, etc.)

  alt messages.total is falsy (0/undefined)
    note over Src: New/changed: Skip staleness and history
    Src-->>User: Exit without historical fetch or new message checks
  else messages.total is truthy
    note over Src: New/changed: Guarded logic proceeds
    Src->>Src: hasNewMessages(box): check box.messages.total && staleness
    opt Historical backfill
      Src->>IMAP: Fetch historical messages
      IMAP-->>Src: Message list
      Src-->>User: Emit historical events
    end
  end

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

I twitch my ears at version ticks,
Guarding boxes, counting tricks.
If no mail rests, I hop on by—
No history to fetch or try.
Dependencies fresh, my whiskers preen;
0.0.6—so swift, so clean!
✅ A tidy burrow in IMAP green.

Pre-merge checks and finishing touches

❌ Failed checks (3 warnings)

Check name	Status	Explanation	Resolution
Linked Issues Check	⚠️ Warning	The linked issue requires addressing failures when saving workflows for mailboxes with many messages by handling pagination or resource-loading issues, but the current changes only add guards for empty mailboxes and do not implement pagination or limit processing for large mailboxes.	Implement logic to handle large mailboxes by paginating IMAP fetches or limiting resource loading as described in issue #18604 so that workflows for mailboxes with many messages can be saved and deployed successfully.
Out of Scope Changes Check	⚠️ Warning	The PR includes dependency upgrades such as bumping @pipedream/platform and adding util, which are not related to the bug fix objectives and introduce changes beyond the linked issue’s scope.	Separate dependency version bumps and additions into their own pull request or provide justification for why these upgrades are necessary to support the bug fix in the IMAP new-email source.
Description Check	⚠️ Warning	The PR description only contains a reference to the linked issue and fails to follow the repository’s description template, lacking the required “## WHY” section and details.	Update the pull request description to include the required sections from the template, such as “## WHY” with a summary of the rationale and the implemented changes.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The title succinctly indicates that this pull request implements a bug fix for the IMAP new-email source, which corresponds to the primary change in the code.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

• 📝 Generate Docstrings

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch issue-18604

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 57c0956 and 4d72791.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (2)

• components/imap/package.json (2 hunks)
• components/imap/sources/new-email/new-email.mjs (3 hunks)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)

• GitHub Check: Lint Code Base
• GitHub Check: Verify TypeScript components
• GitHub Check: Publish TypeScript components
• GitHub Check: pnpm publish

🔇 Additional comments (6)

components/imap/package.json (3)

3-3: LGTM!

Version bump to 0.0.6 aligns with the source file changes and follows semantic versioning conventions.

---

16-16: Ensure @pipedream/platform v3 compatibility or remove unused dependency

• No imports of @pipedream/platform found under components/imap—if the package isn’t used, remove it.
• Otherwise, review and update any platform API calls against the v3 migration guide before merging.

---

20-20: util dependency is required
Imported in components/imap/imap.app.mjs and used via util.promisify to wrap connection methods—keep it.

components/imap/sources/new-email/new-email.mjs (3)

79-87: Conditional processing prevents errors with empty or unavailable mailboxes.

Wrapping the historical event processing in if (box.messages.total) prevents attempting to fetch messages when the mailbox is empty or when the total count is unavailable. This is a defensive improvement.

However, this doesn't appear to address pagination or resource limits for mailboxes with large message counts, which was mentioned as a potential cause in issue #18604.

Questions:

1. Is the 25-message limit (lines 80-82) sufficient to prevent resource exhaustion during deployment?
2. Should there be additional safeguards for mailboxes with thousands of messages?
3. Does the IMAP library or platform handle timeouts gracefully during deployment?

Consider testing with:

• An empty mailbox
• A mailbox with exactly 25 messages
• A mailbox with 1000+ messages
• A mailbox where the IMAP server returns malformed metadata

---

12-12: LGTM!

Version bump to 0.0.6 is consistent with the package.json update and follows semantic versioning for bug fixes.

---

53-53: Guard logic doesn’t address “many messages” failure; please verify

• The added box.messages.total && only skips processing when count is falsy—it doesn’t paginate or batch large mailboxes.
• No occurrences of pagination/batching or evidence that box.messages.total can be undefined were found; please check error logs to confirm if metadata was missing or if additional batching logic is needed.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[luancazarine]

Hi @michelle0927, LGTM! Ready for QA!