batch_modify_messages
Apply label updates to multiple Gmail messages at once. Add or remove specific labels in bulk to streamline email organization and improve workflow efficiency.
Instructions
Modify the labels on multiple messages
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| addLabelIds | No | A list of label IDs to add to the messages | |
| ids | Yes | The IDs of the messages to modify | |
| removeLabelIds | No | A list of label IDs to remove from the messages |
Implementation Reference
- src/index.ts:554-559 (handler)The handler function for the batch_modify_messages tool. It uses handleTool to authenticate and call Gmail's users.messages.batchModify API with the provided message IDs and label changes, then formats the response.async (params) => { return handleTool(config, async (gmail: gmail_v1.Gmail) => { const { data } = await gmail.users.messages.batchModify({ userId: 'me', requestBody: { ids: params.ids, addLabelIds: params.addLabelIds, removeLabelIds: params.removeLabelIds } }) return formatResponse(data) }) }
- src/index.ts:550-553 (schema)Input schema using Zod for validating the tool parameters: required 'ids' array and optional 'addLabelIds' and 'removeLabelIds' arrays.ids: z.array(z.string()).describe("The IDs of the messages to modify"), addLabelIds: z.array(z.string()).optional().describe("A list of label IDs to add to the messages"), removeLabelIds: z.array(z.string()).optional().describe("A list of label IDs to remove from the messages") },
- src/index.ts:547-560 (registration)Registration of the batch_modify_messages tool via server.tool(), including name, description, input schema, and handler function.server.tool("batch_modify_messages", "Modify the labels on multiple messages", { ids: z.array(z.string()).describe("The IDs of the messages to modify"), addLabelIds: z.array(z.string()).optional().describe("A list of label IDs to add to the messages"), removeLabelIds: z.array(z.string()).optional().describe("A list of label IDs to remove from the messages") }, async (params) => { return handleTool(config, async (gmail: gmail_v1.Gmail) => { const { data } = await gmail.users.messages.batchModify({ userId: 'me', requestBody: { ids: params.ids, addLabelIds: params.addLabelIds, removeLabelIds: params.removeLabelIds } }) return formatResponse(data) }) } )
- src/index.ts:50-80 (helper)Shared helper function handleTool that manages OAuth2 authentication, Gmail client creation, API call execution, and error handling (including auth-specific errors). Used by batch_modify_messages and all other tools.const handleTool = async (queryConfig: Record<string, any> | undefined, apiCall: (gmail: gmail_v1.Gmail) => Promise<any>) => { try { const oauth2Client = queryConfig ? createOAuth2Client(queryConfig) : defaultOAuth2Client if (!oauth2Client) throw new Error('OAuth2 client could not be created, please check your credentials') const credentialsAreValid = await validateCredentials(oauth2Client) if (!credentialsAreValid) throw new Error('OAuth2 credentials are invalid, please re-authenticate') const gmailClient = queryConfig ? google.gmail({ version: 'v1', auth: oauth2Client }) : defaultGmailClient if (!gmailClient) throw new Error('Gmail client could not be created, please check your credentials') const result = await apiCall(gmailClient) return result } catch (error: any) { // Check for specific authentication errors if ( error.message?.includes("invalid_grant") || error.message?.includes("refresh_token") || error.message?.includes("invalid_client") || error.message?.includes("unauthorized_client") || error.code === 401 || error.code === 403 ) { return formatResponse({ error: `Authentication failed: ${error.message}. Please re-authenticate by running: npx @shinzolabs/gmail-mcp auth`, }); } return formatResponse({ error: `Tool execution failed: ${error.message}` }); } }