modify_gmail_message_labels
Add or remove Gmail message labels to organize emails efficiently. Specify email address and message ID to update labels dynamically.
Instructions
Adds or removes labels from a Gmail message.
Args:
user_google_email (str): The user's Google email address. Required.
message_id (str): The ID of the message to modify.
add_label_ids (Optional[List[str]]): List of label IDs to add to the message.
remove_label_ids (Optional[List[str]]): List of label IDs to remove from the message.
Returns:
str: Confirmation message of the label changes applied to the message.Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| add_label_ids | No | ||
| message_id | Yes | ||
| remove_label_ids | No | ||
| service | Yes | ||
| user_google_email | Yes |
Implementation Reference
- gmail/gmail_tools.py:1257-1306 (handler)The primary handler function that implements the modify_gmail_message_labels tool. It uses the Gmail API to add or remove labels from a specific message.
@handle_http_errors("modify_gmail_message_labels", service_type="gmail") @require_google_service("gmail", GMAIL_MODIFY_SCOPE) async def modify_gmail_message_labels( service, user_google_email: str, message_id: str, add_label_ids: List[str] = Field(default=[], description="Label IDs to add to the message."), remove_label_ids: List[str] = Field(default=[], description="Label IDs to remove from the message."), ) -> str: """ Adds or removes labels from a Gmail message. To archive an email, remove the INBOX label. To delete an email, add the TRASH label. Args: user_google_email (str): The user's Google email address. Required. message_id (str): The ID of the message to modify. add_label_ids (Optional[List[str]]): List of label IDs to add to the message. remove_label_ids (Optional[List[str]]): List of label IDs to remove from the message. Returns: str: Confirmation message of the label changes applied to the message. """ logger.info( f"[modify_gmail_message_labels] Invoked. Email: '{user_google_email}', Message ID: '{message_id}'" ) 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 = {} 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().modify(userId="me", id=message_id, 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"Message labels updated successfully!\nMessage ID: {message_id}\n{'; '.join(actions)}" - gmail/gmail_tools.py:1263-1265 (schema)Pydantic schema definition for the tool's input parameters using Field for validation and descriptions.
add_label_ids: List[str] = Field(default=[], description="Label IDs to add to the message."), remove_label_ids: List[str] = Field(default=[], description="Label IDs to remove from the message."), ) -> str: - gmail/gmail_tools.py:1257-1257 (registration)Decorators that register the function as an MCP tool and apply necessary error handling and authentication scopes.
@handle_http_errors("modify_gmail_message_labels", service_type="gmail") - gmail/gmail_tools.py:1130-1175 (helper)Helper tool to list all Gmail labels, useful for obtaining label IDs needed for modify_gmail_message_labels.
@handle_http_errors("list_gmail_labels", is_read_only=True, service_type="gmail") @require_google_service("gmail", "gmail_read") async def list_gmail_labels(service, user_google_email: str) -> str: """ Lists all labels in the user's Gmail account. Args: user_google_email (str): The user's Google email address. Required. Returns: str: A formatted list of all labels with their IDs, names, and types. """ logger.info(f"[list_gmail_labels] Invoked. Email: '{user_google_email}'") response = await asyncio.to_thread( service.users().labels().list(userId="me").execute ) labels = response.get("labels", []) if not labels: return "No labels found." lines = [f"Found {len(labels)} labels:", ""] system_labels = [] user_labels = [] for label in labels: if label.get("type") == "system": system_labels.append(label) else: user_labels.append(label) if system_labels: lines.append("📂 SYSTEM LABELS:") for label in system_labels: lines.append(f" • {label['name']} (ID: {label['id']})") lines.append("") if user_labels: lines.append("🏷️ USER LABELS:") for label in user_labels: lines.append(f" • {label['name']} (ID: {label['id']})") return "\n".join(lines) - gmail/gmail_tools.py:1178-1255 (helper)Helper tool to create, update, or delete Gmail labels, supporting label management workflow.
@handle_http_errors("manage_gmail_label", service_type="gmail") @require_google_service("gmail", GMAIL_LABELS_SCOPE) async def manage_gmail_label( service, user_google_email: str, action: Literal["create", "update", "delete"], name: Optional[str] = None, label_id: Optional[str] = None, label_list_visibility: Literal["labelShow", "labelHide"] = "labelShow", message_list_visibility: Literal["show", "hide"] = "show", ) -> str: """ Manages Gmail labels: create, update, or delete labels. Args: user_google_email (str): The user's Google email address. Required. action (Literal["create", "update", "delete"]): Action to perform on the label. name (Optional[str]): Label name. Required for create, optional for update. label_id (Optional[str]): Label ID. Required for update and delete operations. label_list_visibility (Literal["labelShow", "labelHide"]): Whether the label is shown in the label list. message_list_visibility (Literal["show", "hide"]): Whether the label is shown in the message list. Returns: str: Confirmation message of the label operation. """ logger.info( f"[manage_gmail_label] Invoked. Email: '{user_google_email}', Action: '{action}'" ) if action == "create" and not name: raise Exception("Label name is required for create action.") if action in ["update", "delete"] and not label_id: raise Exception("Label ID is required for update and delete actions.") if action == "create": label_object = { "name": name, "labelListVisibility": label_list_visibility, "messageListVisibility": message_list_visibility, } created_label = await asyncio.to_thread( service.users().labels().create(userId="me", body=label_object).execute ) return f"Label created successfully!\nName: {created_label['name']}\nID: {created_label['id']}" elif action == "update": current_label = await asyncio.to_thread( service.users().labels().get(userId="me", id=label_id).execute ) label_object = { "id": label_id, "name": name if name is not None else current_label["name"], "labelListVisibility": label_list_visibility, "messageListVisibility": message_list_visibility, } updated_label = await asyncio.to_thread( service.users() .labels() .update(userId="me", id=label_id, body=label_object) .execute ) return f"Label updated successfully!\nName: {updated_label['name']}\nID: {updated_label['id']}" elif action == "delete": label = await asyncio.to_thread( service.users().labels().get(userId="me", id=label_id).execute ) label_name = label["name"] await asyncio.to_thread( service.users().labels().delete(userId="me", id=label_id).execute ) return f"Label '{label_name}' (ID: {label_id}) deleted successfully!"