manageFilter: expose "Apply filter to matching conversations" (retroactive apply)

[ElliotDrel]

Description

Request

Add a way to apply a Gmail filter to existing/matching conversations at create time, the same thing the Gmail web UI offers as the "Also apply filter to matching conversations" checkbox.

Why

manageFilter with action: "create" only affects mail that arrives after the filter exists. Gmail's own UI lets you tick a box and have the filter's actions applied retroactively to everything already in the mailbox that matches the criteria.

Today, an agent that builds or tunes a filter on the user's behalf has to stop and tell the user: "now go into Gmail settings, open the filter, click edit, click continue, tick 'Also apply filter to matching conversations', and save." That is a manual handoff in the middle of an otherwise fully automated workflow, and it's easy for the user to forget, which leaves the filter silently doing nothing to the backlog it was built for.

Suggested shapes

Any of these would solve it:

1. An applyToExisting: boolean option on manageFilter create.
2. A separate action: "apply" that takes an existing filter id and runs its actions over everything currently matching its criteria.
3. Documentation in the tool description stating plainly that filters are forward-only and naming the exact workaround, so the agent at least knows to surface it.

Note on feasibility

I am aware the Gmail API's users.settings.filters resource may not expose the retroactive apply that the web UI performs, in which case this would have to be emulated — run the filter's criteria as a users.messages.list query, then batch-apply the filter's addLabelIds/removeLabelIds via users.messages.batchModify. That emulation has real edge cases (criteria that don't translate cleanly to a search query, forward actions, size/attachment criteria, pagination over large result sets), so I'm leaving the approach to the maintainer. Even option 3 alone would be an improvement over the current silence.

Repro

1. manageFilter create a filter whose criteria match mail already in the mailbox.
2. Search for that criteria.
3. Observe that pre-existing matching messages are untouched; only newly arriving mail gets the filter's actions.

Diagnostic Info

• Server version: 3.4.6
• Node version: v22.22.3
• OS: win32 10.0.26200 (x64)
• Auth status: valid
• Scopes: documents, drive, spreadsheets, script.external_request, gmail.modify, gmail.compose, gmail.send, gmail.settings.basic, gmail.settings.sharing, calendar, forms.body, forms.body.readonly, forms.responses.readonly, presentations, tasks, service.management