batch_modify_gmail_message_labels
Add or remove Gmail labels for multiple messages in a single batch operation. Simplify organizing and categorizing emails efficiently using user-specified label IDs and message IDs.
Instructions
Adds or removes labels from multiple Gmail messages in a single batch request.
Args: user_google_email (str): The user's Google email address. Required. message_ids (List[str]): A list of message IDs to modify. add_label_ids (Optional[List[str]]): List of label IDs to add to the messages. remove_label_ids (Optional[List[str]]): List of label IDs to remove from the messages.
Returns: str: Confirmation message of the label changes applied to the messages.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| add_label_ids | No | Label IDs to add to messages. | |
| message_ids | Yes | ||
| remove_label_ids | No | Label IDs to remove from messages. | |
| user_google_email | Yes |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- gmail/gmail_tools.py:1128-1176 (handler)The core handler function for the 'batch_modify_gmail_message_labels' tool. It is registered via @server.tool(), handles authentication and errors via decorators, and implements the batch label modification logic using the Gmail API's users.messages.batchModify method. Includes input validation via Pydantic Field and a descriptive docstring serving as schema documentation.
@server.tool() @handle_http_errors("batch_modify_gmail_message_labels", service_type="gmail") @require_google_service("gmail", GMAIL_MODIFY_SCOPE) async def batch_modify_gmail_message_labels( service, user_google_email: str, message_ids: List[str], add_label_ids: List[str] = Field(default=[], description="Label IDs to add to messages."), remove_label_ids: List[str] = Field(default=[], description="Label IDs to remove from messages."), ) -> str: """ Adds or removes labels from multiple Gmail messages in a single batch request. Args: user_google_email (str): The user's Google email address. Required. message_ids (List[str]): A list of message IDs to modify. add_label_ids (Optional[List[str]]): List of label IDs to add to the messages. remove_label_ids (Optional[List[str]]): List of label IDs to remove from the messages. Returns: str: Confirmation message of the label changes applied to the messages. """ logger.info( f"[batch_modify_gmail_message_labels] Invoked. Email: '{user_google_email}', Message IDs: '{message_ids}'" ) if not add_label_ids and not remove_label_ids: raise Exception( "At least one of add_label_ids or remove_label_ids must be provided." ) body = {"ids": message_ids} if add_label_ids: body["addLabelIds"] = add_label_ids if remove_label_ids: body["removeLabelIds"] = remove_label_ids await asyncio.to_thread( service.users().messages().batchModify(userId="me", body=body).execute ) actions = [] if add_label_ids: actions.append(f"Added labels: {', '.join(add_label_ids)}") if remove_label_ids: actions.append(f"Removed labels: {', '.join(remove_label_ids)}") return f"Labels updated for {len(message_ids)} messages: {'; '.join(actions)}" - gmail/gmail_tools.py:1128-1128 (registration)The @server.tool() decorator registers this function as an MCP tool named 'batch_modify_gmail_message_labels' (derived from function name).
@server.tool() - gmail/gmail_tools.py:1131-1137 (schema)Function signature with Pydantic Field annotations for input validation and comprehensive docstring defining the tool's schema (parameters, descriptions, types, and return value).
async def batch_modify_gmail_message_labels( service, user_google_email: str, message_ids: List[str], add_label_ids: List[str] = Field(default=[], description="Label IDs to add to messages."), remove_label_ids: List[str] = Field(default=[], description="Label IDs to remove from messages."), ) -> str: