email_bulk_modify_messages
Applies the same organization change — read, starred, labels, archive, or a move — to many messages in one mailbox. Use it for inbox cleanup that should stay reversible, in preference to email_bulk_delete_messages. Archiving a thousand messages can be undone; deleting them cannot. Select with either message_ids or query, never both and never neither, and set max_messages to cap a query selection. One call covers one account only. Large operations run in the background — poll operation_id with email_bulk_operation_get and check failed and skipped before reporting success.
Input fields
{
"type": "object",
"properties": {
"account_id": {
"type": "string",
"minLength": 1,
"description": "The connected mailbox to act on, from email_accounts_list. Never guess this value and never reuse one across mailboxes — it selects both the credential and the permission set the call runs under."
},
"message_ids": {
"description": "Explicit message ids to act on. Supply this or query, never both. Prefer explicit ids: you can show the user exactly what will change.",
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
{
"type": "null"
}
]
},
"query": {
"description": "Select messages by search instead of by id, using the same syntax as email_search_messages. The server resolves and freezes the matching set before it modifies, so later mail is never swept in. Requires Read as well as Write. Run the same query through email_search_messages first and show the user the count.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"changes": {
"type": "object",
"properties": {
"read": {
"description": "true marks read, false marks unread.",
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"starred": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"add_labels": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
{
"type": "null"
}
]
},
"remove_labels": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
{
"type": "null"
}
]
},
"archive": {
"description": "true removes the messages from the inbox.",
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"destination_folder_id": {
"description": "Move every selected message here. A folder id from email_list_folders.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"description": "The changes applied to every selected message. Omitted fields are left alone."
},
"max_messages": {
"description": "Hard ceiling on how many messages this call may touch. Also clamped to the server's own maximum.",
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
},
"idempotency_key": {
"type": "string",
"minLength": 1,
"description": "A unique value you generate for this attempt, e.g. a UUID. Retrying with the same key returns the original result instead of acting twice. Reusing a key with different arguments is an IDEMPOTENCY_CONFLICT."
}
},
"required": [
"account_id",
"changes",
"idempotency_key"
]
}Tool behavior
May change provider state. Check the explicit account, required access and provider capabilities before invoking.
Inspect isError and per-account errors. General write tools do not all enforce exact-plan approval. This reference does not certify any current AI client version.
YOUR INBOXES.
UNDER CONTROL.
Get started Start with a free account and one read-only search. Existing accounts keep their connection.