View as Markdown
Gmail icon

Gmail ACTION

Find Emails

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 — combine operators freely: from:alan@ingen.com is:unread newer_than:7d has:attachment subject:"DNA sequences". Common operators: from:, to:, subject:, has:attachment, filename:pdf, is:unread, is:starred, label:INBOX, newer_than:7d, older_than:1m, after:2025/01/01, before:2025/12/31, category:primary. labelIds accepts either raw label IDs (INBOX, STARRED) or user-visible names (Clients/Acme) — names are resolved server-side via List Labels. Each returned message carries id, threadId, labelIds, the decoded subject/sender/recipient/date, and a snippet. With format: "full" the decoded body text and payload.parts[].body.attachmentId + filename + mimeType are also included — feed those into Download Attachment, or feed threadId into Get Thread for the whole conversation. Set fields on every call to name just what you need — message records are large, and a wide search returns tens of thousands of characters that crowd out the rest of the task. id and threadId are always returned. To BROWSE or COUNT, use ["subject", "sender", "date"]. To READ or SUMMARISE — "catch me up", "what did X say about Y", "is there anything I need to reply to" — use ["subject", "sender", "date", "bodyText"]. bodyText is the decoded plain-text body (HTML converted, MIME scaffolding and attachments stripped), about half the size of the raw payload, and requesting it fetches full messages for you. Never answer a question about what an email SAYS from snippet — it is a fixed ~200-character prefix, so the sentence you need is usually past its end, and nothing in a snippet indicates that it was cut. Where the snippet is all you asked for and content was likely cut, the message carries snippetTruncated: true. format stays metadata unless you need the raw MIME tree for Download Attachment, in which case pass format: "full" and request payload. Responses are capped. Over the cap: if you named fields, whole messages are dropped rather than your chosen fields being removed, and the note says how many of how many are shown — narrow q and retry. If you named none, messages are compacted instead so counts stay accurate. bodyText shrinks toward a floor before anything is dropped, flagging each cut message with bodyTruncated: true. See the documentation and Gmail search operators.
  • Action
  • Read only
  • OAuth
  • SDK
  • MCP

IMPLEMENTATION

Call this tool

Connect a user's Gmail account once, then configure and run Find Emails 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-find-email",
  externalUserId: "{external_user_id}", // any stable ID for this user in your system
  configuredProps: {
    gmail: { authProvisionId: "apn_xxxxxxx" },
    q: "Search Query",
    labelIds: ["Label IDs or Names"],
  },
})

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.

Find Emails inputs
Property Type Description
q Search Query string
Gmail search query using standard search operators. Examples: is:unread newer_than:7d, from:noreply@github.com has:attachment, subject:"Eval-Thread-Test", label:INBOX is:starred. Leave blank to return the most recent messages across the mailbox.
Optional
labelIds Label IDs or Names string[]
Only return messages that carry all of these labels. Accepts either raw label IDs (e.g. INBOX, STARRED, UNREAD, TRASH, SPAM) or user-visible label names (e.g. Clients/Acme) — names are resolved against List Labels before the request is sent.
Optional
includeSpamTrash Include Spam and Trash boolean
Include messages from SPAM and TRASH in results. Defaults to false.
Optional
maxResults Max Results integer
Maximum number of messages to return. Default 25, Gmail API max 500. Lower this for large/busy inboxes to keep responses under the token cap.
Optional
format Format string
metadata (default) — headers + snippet only, much smaller responses. Use this for every "find", "count", "which" query. full — includes decoded body text and attachment IDs. Use only when you need to read message contents or download an attachment.
Optional
fields Fields string[]

Return only these fields on each message, instead of the full record. Always set this unless you genuinely need every field — message records are large, and a wide search can return tens of thousands of characters that crowd out the rest of the task. id and threadId are always included so results can be fed into Get Thread, Modify Labels, or Download Attachment.

Choose by what you are doing:

  • Browsing, counting, "which emails…"["subject", "sender", "date"]. Add labelIds to check read/starred state.
  • Reading, summarising, "catch me up", "what did X say"["subject", "sender", "date", "bodyText"]. bodyText is a derived field: the decoded plain-text body, HTML converted, attachments and MIME scaffolding stripped. It is roughly half the size of payload and is what you want for any question about what an email SAYS. Requesting it fetches full messages automatically — you do not also need format: "full".
  • Downloading an attachment["payload"] with format: "full", then read payload.parts[].body.attachmentId.

Do NOT try to answer a content question from snippet: it is a fixed ~200-character prefix, so the sentence you need is usually past its end, and a snippet gives no sign that anything was cut. Ask for bodyText instead. Omit fields entirely to return the complete message record, exactly as this tool has always done.

Optional
bodyChars Body Characters integer
Maximum characters of bodyText to return per message. Default 2000, which covers a normal one-page email in full. Only applies when bodyText is requested in fields. Any message whose body is cut comes back with bodyTruncated: true and bodyTotalChars (its real length) — re-fetch that single message with a higher limit, or use Get Thread, to read the rest. Raise it for long newsletters or threads; lower it to fit more messages in one response.
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-find-email
Version
0.3.1
App
Gmail
Authentication
OAuth
Read-only
Yes
Destructive
No
Open world
Yes