# Gmail — Pipedream Connect

> Gmail offers private and secure email by Google at no cost, for business and consumer accounts.

- API slug: `gmail` (use in MCP headers and tool keys)
- Auth: OAuth (Pipedream-managed)
- Categories: Communication
- Website: https://mail.google.com
- Managed OAuth scopes: `https://www.googleapis.com/auth/gmail.labels` · `https://www.googleapis.com/auth/gmail.send` · `https://www.googleapis.com/auth/gmail.modify` · `https://www.googleapis.com/auth/gmail.compose` · `https://www.googleapis.com/auth/gmail.settings.basic`
- This page (HTML): https://pipedream.com/apps/gmail
- Tools: 21 actions · 5 triggers

## Connect via MCP (recommended)

- Endpoint: `https://remote.mcp.pipedream.net/v3`
- Headers: `Authorization: Bearer <token>` · `x-pd-project-id` · `x-pd-environment` · `x-pd-external-user-id` · `x-pd-app-slug: gmail`

```ts
import { Client } from "@modelcontextprotocol/sdk/client/index.js"
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"
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 accessToken = await pd.rawAccessToken

const transport = new StreamableHTTPClientTransport(
  new URL("https://remote.mcp.pipedream.net/v3"),
  {
    requestInit: {
      headers: {
        Authorization: `Bearer ${accessToken}`,
        "x-pd-project-id": process.env.PIPEDREAM_PROJECT_ID!,
        "x-pd-environment": "production",
        "x-pd-external-user-id": "{external_user_id}", // any stable ID for this user in your system
        "x-pd-app-slug": "gmail",
      },
    },
  },
)

const mcp = new Client({ name: "my-agent", version: "1.0.0" })
await mcp.connect(transport)

const { tools } = await mcp.listTools()

// e.g. run Add Label to Email:
const result = await mcp.callTool({
  name: "gmail-add-label-to-email",
  arguments: {
    message: "Message",
    addLabelIds: ["Labels"],
  },
})
```

Docs: [MCP guide](https://pipedream.com/docs/connect/mcp/developers.md)

## API proxy

For a Gmail endpoint with no pre-built tool, the proxy forwards your request with the connected user's credentials attached.

```bash
# The path segment is the target URL, URL-safe base64 encoded:
# https://www.googleapis.com/oauth2/v1/userinfo

curl "https://api.pipedream.com/v1/connect/{project_id}/proxy/aHR0cHM6Ly93d3cuZ29vZ2xlYXBpcy5jb20vb2F1dGgyL3YxL3VzZXJpbmZv?external_user_id={external_user_id}&account_id=apn_xxxxxxx" \
  -H "Authorization: Bearer {access_token}" \
  -H "x-pd-environment: production"
```

Docs: [API proxy guide](https://pipedream.com/docs/connect/api-proxy.md)

## SDK

```ts
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-add-label-to-email",
  externalUserId: "{external_user_id}", // any stable ID for this user in your system
  configuredProps: {
    gmail: { authProvisionId: "apn_xxxxxxx" },
    message: "Message",
    addLabelIds: ["Labels"],
  },
})
```

Docs: [Managed auth guide](https://pipedream.com/docs/connect/managed-auth/quickstart.md) · [Tools guide](https://pipedream.com/docs/connect/components.md)

## Actions (21)

### `gmail-add-label-to-email` — Add Label to Email (Write)

Add label(s) to an email message. See the docs

Full schema: https://pipedream.com/apps/gmail/actions/add-label-to-email.md

### `gmail-archive-email` — Archive Email (Write)

Archive an email message. See the documentation

Full schema: https://pipedream.com/apps/gmail/actions/archive-email.md

### `gmail-bulk-archive-emails` — Bulk Archive Emails (Write)

Archive multiple emails at once. See the documentation

Full schema: https://pipedream.com/apps/gmail/actions/bulk-archive-emails.md

### `gmail-create-draft` — Create Draft (Write)

Create an unsent draft in the authenticated Gmail account. Same parameter shape as Send Email — the difference is the message is saved to Drafts instead of being sent. For a reply-draft, pass inReplyToMessageId (from Find Emails / Get Thread); the subject, References, In-Reply-To, and threadId are…

Full schema: https://pipedream.com/apps/gmail/actions/create-draft.md

### `gmail-create-label` — Create Label (Write)

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…

Full schema: https://pipedream.com/apps/gmail/actions/create-label.md

### `gmail-delete-email` — Delete Email (Write)

Moves the specified message to the trash. See the documentation

Full schema: https://pipedream.com/apps/gmail/actions/delete-email.md

### `gmail-delete-label` — Delete Label (Write)

Immediately and permanently delete a user-created label from the authenticated Gmail mailbox, removing it from every message and thread it was applied to. Only user-created labels can be deleted — Gmail's built-in system labels (INBOX, SENT, SPAM, TRASH, etc.) cannot. This deletes the label…

Full schema: https://pipedream.com/apps/gmail/actions/delete-label.md

### `gmail-download-attachment` — Download Attachment (Read-only)

Download a Gmail message attachment to /tmp and return its path + metadata. File Stash syncs the file and exposes a presigned download URL so the caller can retrieve it. Call Find Emails (with format: "full") or Get Thread first — attachment IDs only appear in full-format message reads; each…

Full schema: https://pipedream.com/apps/gmail/actions/download-attachment.md

### `gmail-find-email` — Find Emails (Read-only)

Search the user's Gmail mailbox with Gmail's native query syntax and return matching messages (headers + snippet by default; full bodies when requested). Use this tool for every "find", "search", "list my", or "show me" email intent. The q parameter accepts the full Gmail search operator set…

Full schema: https://pipedream.com/apps/gmail/actions/find-email.md

### `gmail-get-current-user` — Get Current User (Read-only)

Returns the authenticated Gmail user's name, email address, and mailbox stats (total messages and threads). Call this first when the user says 'my emails', 'my inbox', or needs identity context. Use the returned emailAddress to identify the user's own messages in Find Emails results. See the…

Full schema: https://pipedream.com/apps/gmail/actions/get-current-user.md

### `gmail-get-send-as-alias` — Get Send As Alias (Read-only)

Get a send as alias for the authenticated user. See the documentation

Full schema: https://pipedream.com/apps/gmail/actions/get-send-as-alias.md

### `gmail-list-thread-messages` — Get Thread (Read-only)

Fetch an entire Gmail thread (conversation) by thread ID — returns every message in order with headers, decoded body text, and attachment metadata. Use this after Find Emails when the user wants the full conversation rather than a single message. Each result from Find Emails includes a threadId you…

Full schema: https://pipedream.com/apps/gmail/actions/list-thread-messages.md

### `gmail-list-labels` — List Labels (Read-only)

List every label in the authenticated user's mailbox (system labels like INBOX, SENT, TRASH, STARRED, UNREAD and user-created labels). Call this before Modify Labels or Find Emails when you need to target a label that the user named rather than an obvious system label — it resolves a name like…

Full schema: https://pipedream.com/apps/gmail/actions/list-labels.md

### `gmail-list-delegate-options` — List Send as a Delegate Options (Read-only)

Retrieves available options for the Send as a Delegate field.

Full schema: https://pipedream.com/apps/gmail/actions/list-delegate-options.md

### `gmail-list-send-as-aliases` — List Send As Aliases (Read-only)

List all send as aliases for the authenticated user. See the documentation

Full schema: https://pipedream.com/apps/gmail/actions/list-send-as-aliases.md

### `gmail-list-signature-options` — List Signature Options (Read-only)

Retrieves available options for the Signature field.

Full schema: https://pipedream.com/apps/gmail/actions/list-signature-options.md

### `gmail-modify-labels` — Modify Labels (Write)

Add and/or remove labels on one or more Gmail messages in a single call. In Gmail, most inbox-state operations are label mutations under the hood, so this one tool covers archive / trash / untrash / star / unstar / mark-read / mark-unread / apply-label / remove-label.

Full schema: https://pipedream.com/apps/gmail/actions/modify-labels.md

### `gmail-remove-label-from-email` — Remove Label from Email (Write)

Remove label(s) from an email message. See the docs

Full schema: https://pipedream.com/apps/gmail/actions/remove-label-from-email.md

### `gmail-send-email` — Send Email (Write)

Send a new email OR reply to an existing thread from the authenticated Gmail account. For a fresh message, set to/subject/body; leave inReplyToMessageId blank. To reply to a thread, pass the id of any message in that thread as inReplyToMessageId — the tool preserves threading (References…

Full schema: https://pipedream.com/apps/gmail/actions/send-email.md

### `gmail-update-org-signature` — Update Signature for Email in Organization (Write)

Update the signature for a specific email address in an organization. A Google Cloud service account with delegated domain-wide authority is required for this action. See the documentation

Full schema: https://pipedream.com/apps/gmail/actions/update-org-signature.md

### `gmail-update-primary-signature` — Update Signature for Primary Email Address (Write)

Update the signature for the primary email address. See the documentation

Full schema: https://pipedream.com/apps/gmail/actions/update-primary-signature.md

## Triggers (5)

### `gmail-new-attachment-received` — New Attachment Received (Polling)

Emit new event for each attachment in a message received. This source is capped at 100 max new messages per run.

Full schema: https://pipedream.com/apps/gmail/triggers/new-attachment-received.md

### `gmail-new-email-matching-search` — New Email Matching Search (Polling)

Emit new event when an email matching the search criteria is received. This source is capped at 100 max new messages per run.

Full schema: https://pipedream.com/apps/gmail/triggers/new-email-matching-search.md

### `gmail-new-email-received` — New Email Received (Polling)

Emit new event when a new email is received.

Full schema: https://pipedream.com/apps/gmail/triggers/new-email-received.md

### `gmail-new-labeled-email` — New Labeled Email (Polling)

Emit new event when a new email is labeled.

Full schema: https://pipedream.com/apps/gmail/triggers/new-labeled-email.md

### `gmail-new-sent-email` — New Sent Email (Polling)

Emit new event for each new email sent. (Maximum of 100 events emited per execution)

Full schema: https://pipedream.com/apps/gmail/triggers/new-sent-email.md

---

- All apps: https://pipedream.com/apps — index: https://pipedream.com/llms.txt
- Pipedream docs for agents: https://pipedream.com/docs/llms.txt