Move Matching Email Messages
move_messages_matchingMove messages in a folder that match sender addresses and/or an OData filter to a chosen destination, with dry-run preview and a move limit to prevent accidental bulk changes.
Instructions
Move every message in a folder that matches a sender list and/or an OData filter — the bulk step of an inbox clean-up. Pass senders (addresses from summarize_senders) and/or filter; a whole folder with no condition is refused. Destination deleteditems is how to bulk-delete: it is reversible from Deleted Items, and a hard delete is deliberately not offered.
SAFE BY DEFAULT: dry_run is true unless set to false. A dry run fetches the matching set and reports the count, date range, sender breakdown and newest subjects, moving nothing — read it before re-running with dry_run: false. A live run refuses to move more than limit messages (default 1000) so a mis-scoped filter cannot empty a folder; raise limit explicitly when the dry-run count is intended.
Moves go through Graph JSON batching (20 per round-trip, throttling retried), so thousands of messages take seconds, not minutes, and no message IDs pass through the caller.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"folder": "<folder>",
"destination": "<destination>"
},
"name": "move_messages_matching"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Refuse a live run that would move more than this many (default 1000, max 20000) | |
| filter | No | OData filter, e.g. "receivedDateTime lt 2025-01-01T00:00:00Z". Combined with senders using AND. | |
| folder | Yes | Folder to sweep: well-known name (inbox), display name, or ID. Required. | |
| dry_run | No | Default true: report what would move and move nothing. Pass false to move. | |
| mailbox | No | Email address of another mailbox to act on (delegated or shared), e.g. 'someone@example.com'. Omit for your own mailbox; required when this server signs in as an application. Only addresses this server is configured to allow will be accepted. | |
| senders | No | Sender addresses to match, exact and case-insensitive (max 20 per call) | |
| destination | Yes | Where matches go: well-known name (deleteditems, archive, junkemail), display name, or ID |