# Find Email — Microsoft Outlook 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…

- Key: `microsoft_outlook-find-email`
- Type: Action (Read-only)
- Version: 1.1.1
- App: Microsoft Outlook Email (`microsoft_outlook`) — https://pipedream.com/apps/microsoft-outlook.md
- This page (HTML): https://pipedream.com/apps/microsoft-outlook/actions/find-email
- Hints: read-only · open-world
- Source: https://github.com/PipedreamHQ/pipedream/blob/master/components/microsoft_outlook/actions/find-email/find-email.mjs

## Description

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](https://learn.microsoft.com/en-us/graph/api/user-list-messages?view=graph-rest-1.0)

## Props

| Prop | Type | Required | Description |
|---|---|---|---|
| `isRead` | `boolean` | No | 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. |
| `subject` | `string` | No | 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. |
| `from` | `string` | No | Filter by sender email address. Example: sender@example.com. |
| `receivedAfter` | `string` | No | Return messages received on or after this date/time (ISO 8601). Example: 2024-01-01T00:00:00Z. |
| `receivedBefore` | `string` | No | Return messages received on or before this date/time (ISO 8601). Example: 2024-01-31T23:59:59Z. |
| `importance` | `string` | No | Filter by message importance level. |
| `flagged` | `boolean` | No | true returns flagged messages; false returns unflagged messages. |
| `hasAttachments` | `boolean` | No | true returns only messages with attachments; false returns only messages without attachments. |
| `folderScope` | `string` | No | 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. |
| `countOnly` | `boolean` | No | 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. |
| `search` | `string` | No | 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. |
| `filter` | `string` | No | 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. |
| `orderBy` | `string` | No | 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. |
| `maxResults` | `integer` | No | The maximum number of results to return |
| `select` | `string` | No | 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). |
| `includeAttachments` | `boolean` | No | When true, expands attachment metadata in each result. Use Get Message instead when you need a single message's full body and attachments. |
| `userId` | `string` | No | The user ID or UPN of a shared mailbox. Omit to use the authenticated user's mailbox. |
| `sharedFolderId` | `string` | No | 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. |

## Run it

**MCP**

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

**TypeScript**

```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: "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**

```bash
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"
    }
  }'
```

---

- App: https://pipedream.com/apps/microsoft-outlook.md · All apps: https://pipedream.com/apps