Skip to content

feat(search): add from/date filters and require explicit search criteria#33

Open
realugbun wants to merge 2 commits into
codefuturist:mainfrom
realugbun:feat/search-emails-from-and-date-filters
Open

feat(search): add from/date filters and require explicit search criteria#33
realugbun wants to merge 2 commits into
codefuturist:mainfrom
realugbun:feat/search-emails-from-and-date-filters

Conversation

@realugbun

@realugbun realugbun commented May 12, 2026

Copy link
Copy Markdown

Description

Two improvements to search_emails:

  1. New filtersfrom, since, before, sent_since, sent_before.
    The underlying ImapFlow SearchObject already supported all of these;
    only the plumbing was missing. Mirrors the existing to field and the
    equivalent filters already exposed on list_emails.

  2. Reject all-empty calls — previously, search_emails with no query
    and no filters ran client.search({}, { uid: true }), which matches
    every UID in the mailbox. This made the tool indistinguishable from
    list_emails for empty input and silently masked bugs where unknown
    parameter names were stripped by the Zod schema (e.g. a caller passing
    keyword: instead of query: would see a full-mailbox response with
    no hint that their argument had been dropped). Now throws a clear error
    pointing callers to list_emails.

Motivating example

A common ask is "emails from sender X in the last N days." That used to
require list_emails (which already had from + since), even though
search_emails was the more semantically obvious tool for filtered
lookups. After this PR a single call works:

{
  "account": "work",
  "from": "billing@example.com",
  "since": "2026-05-01T00:00:00Z"
}

Or combined with a keyword:

{
  "account": "work",
  "query": "invoice",
  "since": "2026-04-01T00:00:00Z",
  "has_attachment": true
}

Type of change

  • New feature (non-breaking change that adds functionality)
  • Breaking change — search_emails with no filters now errors
  • Bug fix
  • Documentation update
  • Refactor

Checklist

  • Code follows project style (Biome + ESLint — pnpm check passes)
  • pnpm check passes
  • pnpm typecheck passes
  • All unit tests pass (pnpm test) — 155/155, including 5 new
    searchEmails criteria-builder tests
  • Tool description in emails.tool.ts updated to reflect new params

Notes for reviewer

realugbun added 2 commits May 12, 2026 18:29
The search_emails tool exposed `to` but no `from` filter, even though
the underlying IMAP layer (ImapFlow SearchObject) supports both. Adds:

- from:        sender address substring (mirrors existing `to`)
- since:       INTERNALDATE >= date (ISO 8601)
- before:      INTERNALDATE <  date
- sent_since:  Date: header   >= date
- sent_before: Date: header   <  date

All new filters AND with `query` and existing filters, so combinations
like "keyword X in the last 7 days with attachments" are now a single
call instead of requiring list_emails plus client-side post-filtering.

Adds 4 unit tests covering the new criteria-builder paths.
Previously, calling search_emails with no query and no filters silently
ran `client.search({}, { uid: true })`, returning every UID in the
mailbox. This made the tool indistinguishable from list_emails for
empty input — and concealed bugs where filter args were dropped (e.g.
unknown field names stripped by the Zod schema would silently produce
a full-mailbox response with no hint that the argument had been
ignored).

Now rejects with a clear error pointing callers to list_emails:

  search_emails requires at least one of: query, from, to, since,
  before, sent_since, sent_before, has_attachment, larger_than,
  smaller_than, answered. Use list_emails to browse a mailbox without
  filters.

Adds 1 unit test for the rejection path.

BREAKING CHANGE: search_emails with all-empty arguments now throws
instead of returning the full mailbox.
@realugbun realugbun requested a review from codefuturist as a code owner May 12, 2026 22:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add date-based filtering to search (before/after/range)

1 participant