create_filter
Define and apply email filters based on sender, recipient, subject, attachments, or search queries. Automatically organize incoming messages by adding labels, removing labels, or forwarding emails to specified addresses.
Instructions
Creates a filter
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Actions to perform on messages matching the criteria | |
| criteria | Yes | Filter criteria |
Input Schema (JSON Schema)
{
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"action": {
"additionalProperties": false,
"description": "Actions to perform on messages matching the criteria",
"properties": {
"addLabelIds": {
"description": "List of labels to add to messages",
"items": {
"type": "string"
},
"type": "array"
},
"forward": {
"description": "Email address that the message should be forwarded to",
"type": "string"
},
"removeLabelIds": {
"description": "List of labels to remove from messages",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"criteria": {
"additionalProperties": false,
"description": "Filter criteria",
"properties": {
"excludeChats": {
"description": "Whether the response should exclude chats",
"type": "boolean"
},
"from": {
"description": "The sender's display name or email address",
"type": "string"
},
"hasAttachment": {
"description": "Whether the message has any attachment",
"type": "boolean"
},
"negatedQuery": {
"description": "A Gmail search query that specifies criteria the message must not match",
"type": "string"
},
"query": {
"description": "A Gmail search query that specifies the filter's criteria",
"type": "string"
},
"size": {
"description": "The size of the entire RFC822 message in bytes",
"type": "number"
},
"sizeComparison": {
"description": "How the message size in bytes should be in relation to the size field",
"enum": [
"smaller",
"larger"
],
"type": "string"
},
"subject": {
"description": "Case-insensitive phrase in the message's subject",
"type": "string"
},
"to": {
"description": "The recipient's display name or email address",
"type": "string"
}
},
"type": "object"
}
},
"required": [
"criteria",
"action"
],
"type": "object"
}
Implementation Reference
- src/index.ts:1033-1038 (handler)Handler that executes the creation of a Gmail filter using the provided criteria and action parameters via the Gmail API.return handleTool(config, async (gmail: gmail_v1.Gmail) => { const { data } = await gmail.users.settings.filters.create({ userId: 'me', requestBody: params }) return formatResponse(data) }) } )
- src/index.ts:1014-1032 (schema)Zod schema defining the input parameters for the create_filter tool, including criteria and action objects.{ criteria: z.object({ from: z.string().optional().describe("The sender's display name or email address"), to: z.string().optional().describe("The recipient's display name or email address"), subject: z.string().optional().describe("Case-insensitive phrase in the message's subject"), query: z.string().optional().describe("A Gmail search query that specifies the filter's criteria"), negatedQuery: z.string().optional().describe("A Gmail search query that specifies criteria the message must not match"), hasAttachment: z.boolean().optional().describe("Whether the message has any attachment"), excludeChats: z.boolean().optional().describe("Whether the response should exclude chats"), size: z.number().optional().describe("The size of the entire RFC822 message in bytes"), sizeComparison: z.enum(['smaller', 'larger']).optional().describe("How the message size in bytes should be in relation to the size field") }).describe("Filter criteria"), action: z.object({ addLabelIds: z.array(z.string()).optional().describe("List of labels to add to messages"), removeLabelIds: z.array(z.string()).optional().describe("List of labels to remove from messages"), forward: z.string().optional().describe("Email address that the message should be forwarded to") }).describe("Actions to perform on messages matching the criteria") }, async (params) => {
- src/index.ts:1012-1039 (registration)MCP server tool registration for 'create_filter', specifying name, description, input schema, and handler function.server.tool("create_filter", "Creates a filter", { criteria: z.object({ from: z.string().optional().describe("The sender's display name or email address"), to: z.string().optional().describe("The recipient's display name or email address"), subject: z.string().optional().describe("Case-insensitive phrase in the message's subject"), query: z.string().optional().describe("A Gmail search query that specifies the filter's criteria"), negatedQuery: z.string().optional().describe("A Gmail search query that specifies criteria the message must not match"), hasAttachment: z.boolean().optional().describe("Whether the message has any attachment"), excludeChats: z.boolean().optional().describe("Whether the response should exclude chats"), size: z.number().optional().describe("The size of the entire RFC822 message in bytes"), sizeComparison: z.enum(['smaller', 'larger']).optional().describe("How the message size in bytes should be in relation to the size field") }).describe("Filter criteria"), action: z.object({ addLabelIds: z.array(z.string()).optional().describe("List of labels to add to messages"), removeLabelIds: z.array(z.string()).optional().describe("List of labels to remove from messages"), forward: z.string().optional().describe("Email address that the message should be forwarded to") }).describe("Actions to perform on messages matching the criteria") }, async (params) => { return handleTool(config, async (gmail: gmail_v1.Gmail) => { const { data } = await gmail.users.settings.filters.create({ userId: 'me', requestBody: params }) return formatResponse(data) }) } )