Gmail ACTION

Get Thread

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 can pass here. With format: full (default) each message includes decoded text/html bodies and attachment metadata. Use format: metadata to skip bodies and get only headers + labelIds — useful for large threads. Responses are capped. An oversized thread is served as text: each message keeps subject, sender, recipient, date, and a decoded plain-text bodyText in place of payload (attachment metadata is omitted), shortened toward a floor if needed (cut messages carry bodyTruncated: true and bodyTotalChars). Only if that still does not fit does it fall back to metadata, then drop messages from the tail. Every fallback sets truncated, servedFormat, and a note. Pass includeLinks: false to drop link URLs and images from the decoded text, which keeps notification and newsletter threads far smaller. See the documentation.

Action
Read only
OAuth
SDK
MCP

Start building

IMPLEMENTATION

Call this tool

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

Pipedream Connect

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-list-thread-messages",
  externalUserId: "{external_user_id}", // any stable ID for this user in your system
  configuredProps: {
    gmail: { authProvisionId: "apn_xxxxxxx" },
    threadId: "Thread ID",
    format: "Format",
  },
})

console.log(result)

curl -X POST https://api.pipedream.com/v1/connect/{project_id}/actions/run \
  -H "Content-Type: application/json" \
  -H "X-PD-Environment: production" \
  -H "Authorization: Bearer {access_token}" \
  -d '{
    "external_user_id": "{external_user_id}",
    "id": "gmail-list-thread-messages",
    "configured_props": {
      "gmail": { "authProvisionId": "apn_xxxxxxx" },
      "threadId": "Thread ID",
      "format": "Format"
    }
  }'

// accessToken: mint a short-lived token with the Connect SDK — see the MCP guide
const transport = new StreamableHTTPClientTransport(
  new URL("https://remote.mcp.pipedream.net/v3"),
  {
    requestInit: {
      headers: {
        Authorization: `Bearer ${accessToken}`,
        "x-pd-project-id": "{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()

// listTools() hands your model this tool's input schema, so it can
// fill the arguments itself:
const result = await mcp.callTool({
  name: "gmail-list-thread-messages",
  arguments: {
    threadId: "Thread ID",
    format: "Format",
  },
})

SCHEMA

Inputs

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

Get Thread inputs
Property	Type	Description
`threadId` Thread ID	`string`	The thread identifier. Obtain this from the `threadId` field on a message returned by Find Emails. Required
`format` Format	`string`	`full` (default) returns each message with headers and decoded bodies. `metadata` returns only headers + labelIds (no body, no attachments) — use when the thread is long and you only need to enumerate its messages. Optional
`includeLinks` Include Links	`boolean`	Keep link URLs and image URLs in decoded body text. Defaults to `true`. Set `false` to read what the messages say: links are often most of a newsletter's or notification's text, so more of the thread fits in one response. Keep `true` when you need a URL from the email, such as an unsubscribe, approval, or document link. 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-list-thread-messages
Version: 0.3.1
App: Gmail
Authentication: OAuth
Read-only: Yes
Destructive: No
Open world: Yes
Source: View on GitHub ↗

Call this tool #

Inputs #

Tool details #

Call this tool

Inputs

Tool details