Organize Email
email_organizeDestructive
Move, copy, flag, or archive emails in one inbox. Search and move multiple messages to a target folder for efficient mailbox organization.
Instructions
Move, copy, flag or archive messages in one inbox. Get message ids from email_read first. On Gmail a move adds the destination label and removes INBOX, leaving other labels in place. Needs manage:folders; deleting is the separate email_delete tool.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cc | No | Cc recipient to match: address, name, or fragment. | |
| to | No | To recipient to match: address, name, or fragment. | |
| body | No | Text to find in the body. On Gmail this matches the whole message. | |
| from | No | Sender to match: address, name, or fragment. | |
| text | No | Text to match anywhere, headers included. | |
| inbox | No | Inbox email address; an alternative to inbox_id, which wins when both are given. | |
| limit | No | Cap on messages moved. Default 500. | |
| query | No | Provider-native raw query (escape hatch); prefer the structured fields. Ignored on Fastmail. | |
| since | No | Received on or after this date or datetime (no timezone = UTC). | |
| action | Yes | Operation to run. move = one message_id to destination_folder_id; move_batch = the same for up to 500 message_ids; copy = duplicate into destination_folder_id, original stays, IMAP/Outlook/Fastmail only (never Gmail); copy_batch = the same for up to 500 message_ids; flag = set read/unread/flagged on message_ids via flag_action; archive = move one message_id out of the Inbox; search_and_move = move everything matching a search, the only action the search filters apply to. | |
| before | No | Received strictly before this date or datetime (no timezone = UTC). | |
| unread | No | true = unread only; false = read only; omit for both. | |
| flagged | No | true = only flagged/starred messages. Ignored on Outlook. | |
| subject | No | Text to match in the subject; phrases match as-is. | |
| inbox_id | No | Inbox UUID. Optional when the key has exactly one inbox. Otherwise pass this or `inbox`; omit both and the error lists every inbox_id. | |
| message_id | No | Provider-native message id from a list or search. | |
| flag_action | No | State to apply to every listed message; flag/unflag add or remove the star. | |
| message_ids | No | Provider-native message ids to move. | |
| has_attachment | No | true = only messages with an attachment. Ignored on generic IMAP. | |
| idempotency_key | No | Opaque key for one operation, outbound or mailbox mutation. Reuse it only when retrying the identical request within 24 hours: the retry is collapsed, not repeated, which matters most for copy. Reuse with different arguments is rejected; omit it for normal behaviour. | |
| include_folders | No | Folder names to search. IMAP covers INBOX only when omitted. | |
| destination_folder_id | No | Target folder: an alias (inbox, sent, drafts, trash, archive, spam), a folder name, or a folder id. Names and aliases resolve for you. |