Gmail ACTION

Download Attachment

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 fields: ["subject", "attachments"], or Get Thread, first: each returned message lists its attachments as attachments: [{ partId, filename, mimeType, size }]. Pass the message's id as messageId and the attachment's partId as partId. This works for any message size, including large HTML emails whose payload is too big to return. Alternatively pass attachmentId from a message's payload.parts[].body.attachmentId. Provide partId or attachmentId; when both are given, partId is used. When only attachmentId is given, Gmail issues a new one for the same part on every read, so the filename and MIME type are resolved separately: by partId, then by a unique filename-and-size match, then by a unique size match. If none resolve, the file is saved as attachment-<id> with an extension detected from its contents. If filename is omitted, the action uses the attachment's own filename from the message. Set convertToPdf: true to convert image / HTML / plain-text / DOCX attachments to PDF during download; other MIME types are rejected. 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 Download Attachment 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-download-attachment",
  externalUserId: "{external_user_id}", // any stable ID for this user in your system
  configuredProps: {
    gmail: { authProvisionId: "apn_xxxxxxx" },
    messageId: "Message ID",
    partId: "Part ID",
  },
})

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-download-attachment",
    "configured_props": {
      "gmail": { "authProvisionId": "apn_xxxxxxx" },
      "messageId": "Message ID",
      "partId": "Part ID"
    }
  }'

// 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-download-attachment",
  arguments: {
    messageId: "Message ID",
    partId: "Part ID",
  },
})

SCHEMA

Inputs

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

Download Attachment inputs
Property	Type	Description
`messageId` Message ID	`string`	The `id` of the message containing the attachment, e.g. `19a2b3c4d5e6f789`. Obtain this from Find Emails or Get Thread. Required
`partId` Part ID	`string`	The attachment's `partId` from the message's `attachments` list, e.g. `1` or `0.2`. Get it from Find Emails with `fields: ["subject", "attachments"]`, or from Get Thread. Stable across reads of the message. Required unless `attachmentId` is set. Optional
`attachmentId` Attachment ID	`string`	The attachment's ID from a message's `payload.parts[].body.attachmentId`, a long opaque string such as `ANGjdJ8wX0kL...` (returned by Find Emails with `format: "full"` and `payload` requested, or by Get Thread). Not needed when `partId` is set, and prefer `partId`: on large messages the `payload` holding this ID can be dropped to fit the response cap. Optional
`filename` Filename	`string`	Filename to save in `/tmp` (include the extension, e.g. `report.pdf`). Pass the part's `filename` when you have it. If omitted, the action resolves it from the message payload (see `partId`). Optional
`convertToPdf` Convert to PDF	`boolean`	When true, convert the attachment to a PDF. Supported source MIME types: image/*, text/html, text/plain, and DOCX (`application/vnd.openxmlformats-officedocument.wordprocessingml.document`). Other types throw. Optional
`syncDir` SyncDir	`dir`	Required

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-download-attachment
Version: 0.3.0
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