Microsoft Outlook Email ACTION

Find Email

Find (search, list, or count) email messages in a Microsoft Outlook mailbox via Microsoft Graph. By default a search or list request (countOnly = false) scans the WHOLE mailbox (all folders including Sent, Archive, etc.), matching what you see when searching in Outlook; a count-only request (countOnly = true) with no explicit folderScope stays inbox-scoped and counts ALL inbox messages by default, not just unread ones — also set isRead to false to count only unread messages (matching Outlook's unread inbox badge). Set folderScope explicitly to override this behavior for either mode. To search a shared mailbox, set userId (the mailbox owner's UPN or ID); add sharedFolderId to target a specific folder within it. See the documentation

Action
Read only
OAuth
SDK
MCP

Start building

IMPLEMENTATION

Call this tool

Connect a user's Microsoft Outlook Email account once, then configure and run Find Email 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: "microsoft_outlook-find-email",
  externalUserId: "{external_user_id}", // any stable ID for this user in your system
  configuredProps: {
    microsoft_outlook: { authProvisionId: "apn_xxxxxxx" },
    isRead: true,
    subject: "Subject",
  },
})

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": "microsoft_outlook-find-email",
    "configured_props": {
      "microsoft_outlook": { "authProvisionId": "apn_xxxxxxx" },
      "isRead": true,
      "subject": "Subject"
    }
  }'

// 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": "microsoft_outlook",
      },
    },
  },
)

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: "microsoft_outlook-find-email",
  arguments: {
    isRead: true,
    subject: "Subject",
  },
})

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 Email inputs
Property	Type	Description
`isRead` Is Read	`boolean`	Filter by read/unread status. `false` finds unread messages; `true` finds read messages. Adds `isRead eq {value}` to the OData filter automatically. Can be combined with `search` — when both are set, `search` is automatically converted to a `contains(subject,...)` filter and joined with the `isRead` condition. Optional
`subject` Subject	`string`	Filter messages whose subject contains this text. Example: `project update`. Adds `contains(subject,'...')` to the OData filter. Cannot be combined with `search`. Can be combined with `orderBy`, but Graph requires the sort property to also be filtered — see `Order By`. Optional
`from` From	`string`	Filter by sender email address. Example: `sender@example.com`. Optional
`receivedAfter` Received After	`string`	Return messages received on or after this date/time (ISO 8601). Example: `2024-01-01T00:00:00Z`. Optional
`receivedBefore` Received Before	`string`	Return messages received on or before this date/time (ISO 8601). Example: `2024-01-31T23:59:59Z`. Optional
`importance` Importance	`string`	Filter by message importance level. Optional
`flagged` Flagged	`boolean`	`true` returns flagged messages; `false` returns unflagged messages. Optional
`hasAttachments` Has Attachments	`boolean`	`true` returns only messages with attachments; `false` returns only messages without attachments. Optional
`folderScope` Folder Scope	`string`	Which mailbox folder to scope the query to. Leave blank to use intent-based defaulting: a search/list request (Count Only = false) scans the WHOLE mailbox (all folders); a count-only request (Count Only = true) is scoped to the inbox and counts all inbox messages by default (add `Is Read: false` for an unread-only count matching Outlook's unread inbox badge). Set explicitly to override: `all` scans the whole mailbox regardless of Count Only, or pick a well-known folder (`inbox`, `sentitems`, `drafts`, `deleteditems`, `junkemail`, `archive`). Closed option set; no value is removed or renamed. Optional
`countOnly` Count Only	`boolean`	When `true`, returns `{ count: N }` using a single `$count` API call instead of paginating. Counts all messages in scope by default (inbox-scoped unless `Folder Scope` is set) — also set `Is Read` to `false` for an unread-only count (e.g. to match Outlook's unread inbox badge). Cannot be combined with `search`. Optional
`search` Search	`string`	Search for an email in Microsoft Outlook. Can search for specific message properties such as `"to:example@example.com"` or `"subject:example"`. If the property is excluded, the search targets the default properties `from`, `subject`, and `body`. For example, `"pizza"` will search for messages with the word `pizza` in the subject, body, or from address, but `"to:example@example.com"` will only search for messages to `example@example.com`. Not for use with `$filter` or `$orderby`. Response will not include total message count if `search` is used. Optional
`filter` Filter	`string`	OData filter expression. Example: `contains(subject, 'meeting')` or `receivedDateTime ge 2024-01-01T00:00:00Z`. When combined with `isRead`, filters are joined with `and`. Cannot be combined with `search`. When combined with `orderBy`, Graph's filter/orderby ordering rules are your responsibility — this action cannot introspect a raw filter to reorder it. See filter documentation. Optional
`orderBy` Order By	`string`	Order results by a message property. Example: `receivedDateTime desc` (newest first). Microsoft Graph requires every property in `$orderby` to also appear in `$filter`, before any properties that don't — this action arranges the filter automatically, so pair `orderBy` with a matching filter (e.g. sort by `receivedDateTime` together with a `Received After`/`Received Before` value). Sorting by a property that isn't filtered returns an `InefficientFilter` error. Cannot be combined with `search`. Optional
`maxResults` Max Results	`integer`	The maximum number of results to return Optional
`select` Select Fields	`string`	Comma-separated message property names to include in results, e.g. `id,subject,from,receivedDateTime,isRead`. Leave empty to use the action's default field set (metadata only, excludes body/bodyPreview). Optional
`includeAttachments` Include Attachments	`boolean`	When `true`, expands attachment metadata in each result. Use Get Message instead when you need a single message's full body and attachments. Optional
`userId` User ID	`string`	The user ID or UPN of a shared mailbox. Omit to use the authenticated user's mailbox. Optional
`sharedFolderId` Shared Folder ID	`string`	The ID of a folder in a shared mailbox. Requires `userId` to be set. Routes the search to `/users/{userId}/mailFolders/{sharedFolderId}/messages`. Not for use with `folderScope`. 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: microsoft_outlook-find-email
Version: 1.1.1
App: Microsoft Outlook Email
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