View as Markdown
Gmail icon

Gmail ACTION

Create Label

Create a new user label in the authenticated Gmail mailbox and return its ID. Call this before Modify Labels whenever the label the user wants to apply doesn't yet exist — List Labels will tell you what's already there. Idempotent: if a label with the same name already exists, the action swallows the 409, looks it up by name, and returns the existing label with alreadyExisted: true so the caller can proceed. Nested labels are expressed with / — e.g. Clients/Acme creates or targets a sub-label under Clients. color is optional; when provided, both textColor and backgroundColor must be supplied together and must come from Gmail's fixed palette. 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 Label 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-label",
  externalUserId: "{external_user_id}", // any stable ID for this user in your system
  configuredProps: {
    gmail: { authProvisionId: "apn_xxxxxxx" },
    name: "Name",
    labelListVisibility: "Label List Visibility",
  },
})

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 Label inputs
Property Type Description
name Name string
The display name of the label. Use / to create a nested label (e.g. Clients/Acme). Must be unique within the mailbox.
Required
labelListVisibility Label List Visibility string
Visibility of the label in the sidebar. Defaults to labelShow.
Optional
messageListVisibility Message List Visibility string
Whether messages with this label show the label chip in the list view. Defaults to show.
Optional
textColor Text Color string
Optional text color (must come from Gmail's fixed palette). If set, backgroundColor must also be set.
Optional
backgroundColor Background Color string
Optional background color (must come from Gmail's fixed palette). If set, textColor must also be set.
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-label
Version
0.1.3
App
Gmail
Authentication
OAuth
Read-only
No
Destructive
No
Open world
Yes