CONNECT APP
Build with Microsoft Outlook Email
Communication
- OAuth
MCP
Give your agent Microsoft Outlook Email tools
Every Microsoft Outlook Email action is exposed as an MCP tool on Pipedream's remote server. Point a client at it with your end user's ID and Connect resolves that user's Microsoft Outlook Email account for each tool call — you store no tokens.
// 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()
// e.g. run Add Label to Email:
const result = await mcp.callTool({
name: "microsoft_outlook-add-label-to-email",
arguments: {
userId: "User ID",
messageId: "Message ID",
},
})# access_token: mint a short-lived token with the Connect SDK — see the MCP guide
headers = {
"Authorization": f"Bearer {access_token}",
"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",
}
async with streamablehttp_client("https://remote.mcp.pipedream.net/v3", headers=headers) as (read, write, _):
async with ClientSession(read, write) as session:
await session.initialize()
tools = await session.list_tools()
# e.g. run Add Label to Email:
result = await session.call_tool("microsoft_outlook-add-label-to-email", {
"userId": "User ID",
"messageId": "Message ID",
})API PROXY
Call the Microsoft Outlook Email API directly
For an endpoint with no pre-built tool, the Connect proxy forwards your request to the Microsoft Outlook Email API with the connected user's credentials attached. You store no tokens and write no refresh logic.
const resp = await pd.proxy.get({
externalUserId: "{external_user_id}", // any stable ID for this user in your system
accountId: "apn_xxxxxxx",
url: "https://graph.microsoft.com/v1.0/me",
})
// Any allowed Microsoft Outlook Email endpoint works here. Pipedream attaches the
// connected account's credentials to the outgoing request.# The path segment is the target URL, URL-safe base64 encoded:
# https://graph.microsoft.com/v1.0/me
curl "https://api.pipedream.com/v1/connect/{project_id}/proxy/aHR0cHM6Ly9ncmFwaC5taWNyb3NvZnQuY29tL3YxLjAvbWU?external_user_id={external_user_id}&account_id=apn_xxxxxxx" \
-H "Authorization: Bearer {access_token}" \
-H "x-pd-environment: production"SDK
Run Microsoft Outlook Email actions from your backend
Connect a user's Microsoft Outlook Email account once, then run Add Label to Email on their behalf from your own code — TypeScript, Python, or plain HTTP.
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-add-label-to-email",
externalUserId: "{external_user_id}", // any stable ID for this user in your system
configuredProps: {
microsoft_outlook: { authProvisionId: "apn_xxxxxxx" },
userId: "User ID",
messageId: "Message ID",
},
})from pipedream import Pipedream
pd = Pipedream(
client_id="{oauth_client_id}",
client_secret="{oauth_client_secret}",
project_id="{project_id}",
project_environment="production",
)
result = pd.actions.run(
id="microsoft_outlook-add-label-to-email",
external_user_id="{external_user_id}", # any stable ID for this user in your system
configured_props={
"microsoft_outlook": {"authProvisionId": "apn_xxxxxxx"},
"userId": "User ID",
"messageId": "Message ID",
},
)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-add-label-to-email",
"configured_props": {
"microsoft_outlook": { "authProvisionId": "apn_xxxxxxx" },
"userId": "User ID",
"messageId": "Message ID"
}
}'TOOLS
Microsoft Outlook Email actions
On-demand operations your product or agent can configure and run on behalf of a connected user.
-
Add Label to Email
actionAdds a label/category to an email in Microsoft Outlook. See the documentationWritev0.0.27 -
Create Contact
actionAdd a contact to the root Contacts folder, See the documentationWritev0.0.34 -
Create Draft Email
actionCreate a draft email, See the documentationWritev0.0.35 -
Create Draft Reply
actionCreate a draft reply to an email. See the documentationWritev0.0.12 -
Download Attachment
actionDownload an email attachment to/tmp. Use Find Email to locate the message, then Get Message withincludeAttachments: trueto get themessageIdand attachmentidfields. Example: afterget-message(messageId="AAMk...", includeAttachments=true)returnsattachments: [{ id: "AQMk...", name: "report.pdf" }], calldownload-attachment(messageId="AAMk...", attachmentId="AQMk...", filename="report.pdf")→ writes to/tmp/report.pdf. SetconvertToPdf: trueto convert images, HTML, plain text, or DOCX files to PDF. For text attachments (text/*, JSON), the response includesfileContentwith the decoded text (truncated at 100 KB, flagged bycontentTruncated), so the content can be read directly without fetching the file. See the documentationRead-onlyv0.1.5 -
Find Contacts
actionSearch and list contacts in the authenticated user's Outlook contacts. Returns{ count, contacts }wherecountis the Graph-reported total contact count (@odata.count) andcontactsis the filtered result array. OmitsearchStringto return all contacts up tomaxResults. WhensearchStringis provided, filters contacts by displayName, givenName, surname, or email address (case-sensitive substring match). Important:maxResultsnow bounds how many contacts are fetched from Graph before filtering — contacts beyond that window will not be searched. Example:find-contacts(searchString="George Costanza", maxResults=200)→ scans the first 200 contacts and returns matches. Example:find-contacts(searchString="george@vandelay.com")→ matches by email address. Use the returned contactidwith Save Contact to update the contact. See the documentationRead-onlyv1.0.2 -
Find Email
actionFind (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 explicitfolderScopestays inbox-scoped and counts ALL inbox messages by default, not just unread ones — also setisReadtofalseto count only unread messages (matching Outlook's unread inbox badge). SetfolderScopeexplicitly to override this behavior for either mode. To search a shared mailbox, setuserId(the mailbox owner's UPN or ID); addsharedFolderIdto target a specific folder within it. See the documentationRead-onlyv1.1.1 -
Find Shared Folder Email
actionSearch for an email in a shared folder in Microsoft Outlook. See the documentationRead-onlyv0.0.19 -
Get Current User
actionReturns the authenticated Microsoft user's ID, display name, email, and principal name via Microsoft Graph. Call this first when the user says 'my emails', 'my inbox', or needs identity context. Use the returnedidto scope queries in Find Email or identify the sender in email results. See the documentation.Read-onlyv0.0.7 -
Get Folder
actionRetrieve a single mail folder by its ID. Returns the folder'sid,displayName,parentFolderId,childFolderCount,totalItemCount, andunreadItemCount. If you only have a display name and need the ID, use List Folders first. See the documentationRead-onlyv0.0.5 -
Get Message
actionFetch a single email message by its Microsoft Graph message ID, including full body and optional attachments. Use Find Email first to search for messages and obtain a messageid; then call this tool to retrieve the full content. SetincludeAttachments: trueto expand attachment metadata — theidfield of each attachment is required by Download Attachment. Example: afterfind-email(search="Eval-Festivus")returns a message withid: "AAMk...", callget-message(messageId="AAMk...", includeAttachments=true)to get the body text and attachment list. See the documentationRead-onlyv0.0.7 -
Get Shared Folder
actionRetrieve a single folder from a shared mailbox by its ID. Returns the folder'sid,displayName,parentFolderId,childFolderCount,totalItemCount, andunreadItemCount. If you only have a display name and need the ID, use List Shared Folders first. See the documentationRead-onlyv0.0.5 -
List Contact Options
actionRetrieves available options for the Contact field.Read-onlyv0.0.6 -
List Contacts
actionGet a contact collection from the default contacts folder. Returns{ count, contacts }wherecountis the true total number of contacts in the collection as reported by Microsoft Graph (@odata.count), andcontactsis the array of retrieved contact records (up tomaxResults). See the documentationRead-onlyv1.0.2 -
List Folder IDs to Monitor Options
actionRetrieves available options for the Folder IDs to Monitor field.Read-onlyv0.0.6 -
List Folders
actionRetrieves mail folders for the authenticated user. Returns{ count, folders }wherefolderscontains each folder'sid,displayName,parentFolderId,childFolderCount,totalItemCount, andunreadItemCount. Thecountfield reflects the true API total when Microsoft Graph returns@odata.count(supported for top-level mailFolders queries); whenInclude Subfoldersistrueor Graph does not return@odata.countfor the requested filter,countequals the number of folders actually retrieved. Use this action to resolve a folder display name to its ID — setDisplay Nameto filter by exact name. Use Get Folder instead when you already have the folder ID. See the documentationRead-onlyv1.0.2 -
List Important Mail
actionGet the most important mail from the user's Inbox (messages with high importance or flagged status). Returns{ count, data }wherecountis the true total matching message count reported by Microsoft Graph (@odata.countfor the applied filter) anddatais the array of retrieved messages (up tomaxResults). See the documentationRead-onlyv0.1.2 -
List Labels
actionGet all the labels/categories that have been defined for a user. See the documentationRead-onlyv0.0.27 -
List Shared Folders
actionRetrieves mail folders from a shared or delegated mailbox (routes to/users/{userId}/mailFolders). Returns{ count, folders }wherefolderscontains each folder'sid,displayName,parentFolderId,childFolderCount,totalItemCount, andunreadItemCount. Thecountfield reflects the true API total when Microsoft Graph returns@odata.count; whenInclude Subfoldersistrueor Graph does not return@odata.countfor the requested filter,countequals the number of folders actually retrieved. Use this action to resolve a shared mailbox folder display name to its ID — setDisplay Nameto filter by exact name. Use Get Shared Folder instead when you already have the folder ID. See the documentationRead-onlyv1.0.2 -
Modify Email
actionApply one or more state mutations to an email message: mark read/unread, add/remove categories, move to a folder, or change the flag status. All params exceptmessageIdare optional — only the ones you provide are applied. Use Find Email to obtain a messageidbefore modifying. Recipes: Mark read:isRead: true| Mark unread:isRead: falseAdd category:addCategories: ["Follow Up"]| Remove category:removeCategories: ["Follow Up"]Move to archive:destinationFolderId: "archive"| Move to inbox:destinationFolderId: "inbox"Flag:flagStatus: "flagged"| Unflag:flagStatus: "notFlagged"| Mark complete:flagStatus: "complete"Example:modify-email(messageId="AAMk...", isRead=true)→ marks the message as read. Example:modify-email(messageId="AAMk...", addCategories=["Eval-Seinfeld"], destinationFolderId="archive")→ adds a category AND moves to archive in a single call. See the documentationWritev0.0.6 -
Move Email to Folder
actionMoves an email to the specified folder in Microsoft Outlook. See the documentationWritev0.0.25 -
Remove Label from Email
actionRemoves a label/category from an email in Microsoft Outlook. See the documentationWritev0.0.27 -
Reply to Email
actionReply to an email in Microsoft Outlook. See the documentationWritev0.0.25 -
Save Contact
actionCreate or update an Outlook contact (upsert). OmitcontactIdto create a new contact; providecontactIdto update an existing one. Use Find Contacts first to look up a contact'sidbefore updating. Example (create):save-contact(givenName="Cosmo", surname="Kramer", emailAddresses=["kramer@kramerica.com"])→ creates contact, returns new contact object withid. Example (update):save-contact(contactId="AQMk...", businessPhones=["+1-555-0100"])→ patches the existing contact. See the create documentation See the update documentationWritev0.0.6 -
Send Email
actionSend a new email, reply to an existing message, or save a draft — all in one tool. OmitinReplyToMessageIdto send a new email. ProvideinReplyToMessageIdto reply to an existing message (threads correctly). SetisDraft: trueto save to Drafts instead of sending immediately. Attach files by passing URLs or/tmppaths tofiles. Example (send new):send-email(recipients=["you@example.com"], subject="Hello", content="Hi there")Example (reply):send-email(inReplyToMessageId="AAMk...", content="Thanks for your note")Example (draft):send-email(recipients=["boss@example.com"], subject="Weekly report", content="...", isDraft=true)Use Find Email to locate a messageidbefore replying. See the documentationWritev0.1.5 -
Update Contact
actionUpdate an existing contact, See the docsWritev0.0.34
EVENTS
Microsoft Outlook Email triggers
Event sources your backend can deploy for users and receive through a webhook.
-
New Attachment Received (Instant)
triggerEmit new event when a new email containing one or more attachments arrives in a specified Microsoft Outlook folder.v0.1.22 -
New Contact Event (Instant)
triggerEmit new event when a new Contact is createdv0.0.35 -
New Email Event (Instant)
triggerEmit new event when an email is received in specified folders.v0.1.22 -
New Email in Shared Folder Event
triggerEmit new event when an email is received in specified shared folders.v0.0.21
MULTI-APP
Use Microsoft Outlook Email with other popular apps
Most products don't stop at one integration. Pair Microsoft Outlook Email with the other apps your users rely on, and ship use cases that span both.
REFERENCE
App details
Reference metadata for the Microsoft Outlook Email connector in the Pipedream registry.
- App slug
- microsoft_outlook
- Authentication
- OAuth
- Categories
- Communication
- Actions
- 26
- Triggers
- 4
- API proxy
- Available
OAuth scopes
These are the scopes Pipedream's managed Microsoft Outlook Email OAuth client requests when one of your users connects an account. Supply your own OAuth client to request a different set.
- User.Read
- offline_access
- openid
- profile
- Mail.ReadWrite
- Mail.Send
- Contacts.ReadWrite
- User.ReadBasic.All