View as Markdown
Gmail icon

Gmail ACTION

Create Filter

Create a Gmail filter that automatically acts on incoming mail matching the given criteria. Provide at least one criterion and at least one action. Criteria are combined with AND: a message must match every criterion you set. Actions apply only to mail that arrives after the filter is created; existing messages are not touched. Example — skip the inbox for cancelled-event notices that were not on the user's calendar: from = calendar-notification@google.com, query = "This event has been canceled", negatedQuery = "removed from your calendar", removeLabelIds = ["INBOX"]. Label IDs must be IDs, not names — use List Labels to resolve a label name to its ID (system labels like INBOX, STARRED, UNREAD, TRASH can be used directly). Use List Filters first to avoid creating duplicates. See the documentation.
  • Action
  • Writes data
  • OAuth
  • SDK
  • MCP

IMPLEMENTATION

Call this tool

Connect a user's Gmail account once, then configure and run Create Filter from your backend or agent.

import { PipedreamClient } from "@pipedream/sdk"

const pd = new PipedreamClient({
  projectId: process.env.PIPEDREAM_PROJECT_ID!,
  clientId: process.env.PIPEDREAM_CLIENT_ID!,
  clientSecret: process.env.PIPEDREAM_CLIENT_SECRET!,
  projectEnvironment: "production",
})

const result = await pd.actions.run({
  id: "gmail-create-filter",
  externalUserId: "{external_user_id}", // any stable ID for this user in your system
  configuredProps: {
    gmail: { authProvisionId: "apn_xxxxxxx" },
    from: "From",
    to: "To",
  },
})

console.log(result)

SCHEMA

Inputs

Pipedream supplies the connected account. Your application provides the operation-specific values below. Dynamic inputs are resolved against that user's account.

Create Filter inputs
Property Type Description
from From string
Match messages sent from this sender, e.g. calendar-notification@google.com.
Optional
to To string
Match messages sent to this recipient, e.g. me@example.com.
Optional
subject Subject string
Match messages whose subject contains this text (case-insensitive), e.g. invoice.
Optional
query Has the Words string
Match messages that match this Gmail search query, e.g. "This event has been canceled". Supports the same operators as the Gmail search box (OR, -, quotes, has:, etc.).
Optional
negatedQuery Doesn't Have string
Exclude messages that match this Gmail search query, e.g. "removed from your calendar".
Optional
hasAttachment Has Attachment boolean
If true, only match messages that have an attachment. false has no effect (Gmail ignores it) — to exclude messages with attachments, put has:attachment in Doesn't Have.
Optional
excludeChats Exclude Chats boolean
If true, do not match Google Chat/Hangouts messages. false has no effect (Gmail ignores it).
Optional
size Size (bytes) integer
Message size in bytes to compare against, e.g. 10485760 (10 MB). Requires Size Comparison.
Optional
sizeComparison Size Comparison string
Whether matching messages must be larger or smaller than Size. Requires Size.
Optional
addLabelIds Add Label IDs string[]
IDs of labels to add to matching messages, e.g. ["Label_42", "STARRED"]. Use List Labels to find label IDs.
Optional
removeLabelIds Remove Label IDs string[]
IDs of labels to remove from matching messages. Use INBOX to skip the inbox (archive), UNREAD to mark as read, SPAM to never send to spam.
Optional

REFERENCE

Tool details

Behavior hints are published with the component in the Pipedream registry and surface as MCP tool annotations, so an agent can reason about a tool before it calls it.

Registry key
gmail-create-filter
Version
0.0.1
App
Gmail
Authentication
OAuth
Read-only
No
Destructive
No
Open world
Yes