> ## Documentation Index
> Fetch the complete documentation index at: https://docs.modulex.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Microsoft Outlook Integration for AI Agents & Workflows

> Send, draft, search, and organize email; manage contacts, folders, and categories in Microsoft Outlook via Microsoft Graph.

{/* Self-hosted logo — build-time vendored from modulex.json / Iconify (see scripts/lib/logo.js). */}

<img src="https://mintcdn.com/modulexaillc/df8MOr-hXotYLTh5/logos/microsoft-outlook.svg?fit=max&auto=format&n=df8MOr-hXotYLTh5&q=85&s=f9aae45ad0006b25b74a807bdf7a009a" alt="Microsoft Outlook logo" width="72" height="72" data-path="logos/microsoft-outlook.svg" />

## Overview

Add **Microsoft Outlook** to any ModuleX agent or workflow. Send, draft, search, and organize email; manage contacts, folders, and categories in Microsoft Outlook via Microsoft Graph (`graph.microsoft.com/v1.0`). Uses delegated permissions on behalf of an authenticated Microsoft 365 user.

<Info>
  **Categories**: Communication · Email · Productivity · Communication · Microsoft · **Auth**: OAuth2 · **Actions**: 20
</Info>

## Authentication

### OAuth2 Authentication

Connect with your Microsoft account using OAuth 2.0 against the Microsoft identity platform.

<Steps>
  <Step title="Step 1">
    Register an application at [https://entra.microsoft.com](https://entra.microsoft.com) (Azure AD > App registrations)
  </Step>

  <Step title="Step 2">
    Under 'Authentication', add the redirect URI: [https://api.modulex.dev/credentials/oauth2/callback](https://api.modulex.dev/credentials/oauth2/callback)
  </Step>

  <Step title="Step 3">
    Under 'API permissions', add Microsoft Graph delegated permissions: Mail.ReadWrite, Mail.Send, MailboxSettings.Read, Contacts.ReadWrite, User.Read, User.ReadBasic.All, offline\_access
  </Step>

  <Step title="Step 4">
    Under 'Certificates & secrets', create a new client secret
  </Step>

  <Step title="Step 5">
    Copy the Application (client) ID and the client secret into ModuleX
  </Step>
</Steps>

#### Required Credentials

| Field         | Description                                                          | Required | Format                                 |
| ------------- | -------------------------------------------------------------------- | -------- | -------------------------------------- |
| Client ID     | Microsoft Entra Application (client) ID for the Microsoft Graph app. | Yes      | `00000000-0000-0000-0000-000000000000` |
| Client Secret | Microsoft Entra client secret for the Microsoft Graph app.           | Yes      | `-`                                    |

#### OAuth Configuration

* **Authorization URL**: `https://login.microsoftonline.com/common/oauth2/v2.0/authorize`
* **Token URL**: `https://login.microsoftonline.com/common/oauth2/v2.0/token`
* **Scopes**: `offline_access`, `User.Read`, `User.ReadBasic.All`, `Mail.ReadWrite`, `Mail.Send`, `MailboxSettings.Read`, `Contacts.ReadWrite`

## Available Actions

<AccordionGroup>
  <Accordion title="add_label_to_email — Adds a label/category to an email in Microsoft Outlook.">
    ### Parameters

    <ResponseField name="message_id" type="string" required>
      The identifier of the message to update.
    </ResponseField>

    <ResponseField name="label" type="string" required>
      The name of the label/category to add.
    </ResponseField>

    <ResponseField name="user_id" type="string">
      The User ID of a shared mailbox. If not provided, defaults to the authenticated user's mailbox.
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Id"
        },
        "subject": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Subject"
        },
        "categories": {
          "items": {
            "type": "string"
          },
          "title": "Categories",
          "type": "array"
        }
      },
      "required": [
        "success"
      ],
      "title": "AddLabelToEmailOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="approve_workflow — Send an email containing approve/cancel URLs to a recipient so they can resume or cancel a workflow externally. The caller (workflow engine) is responsible for generating the resume/cancel URLs and passing them in.">
    ### Parameters

    <ResponseField name="recipients" type="array" required>
      Array of recipient email addresses.
    </ResponseField>

    <ResponseField name="subject" type="string" required>
      Subject of the approval email.
    </ResponseField>

    <ResponseField name="resume_url" type="string" required>
      URL the recipient clicks to approve / resume the workflow.
    </ResponseField>

    <ResponseField name="cancel_url" type="string" required>
      URL the recipient clicks to cancel the workflow.
    </ResponseField>

    <ResponseField name="user_id" type="string">
      The User ID of a shared mailbox. If not provided, defaults to the authenticated user's mailbox.
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "sent": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Sent"
        }
      },
      "required": [
        "success"
      ],
      "title": "ApproveWorkflowOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="create_contact — Add a contact to the root Contacts folder.">
    ### Parameters

    <ResponseField name="given_name" type="string">
      Given name of the contact.
    </ResponseField>

    <ResponseField name="surname" type="string">
      Surname of the contact.
    </ResponseField>

    <ResponseField name="email_addresses" type="array">
      Email addresses for the contact (list of strings).
    </ResponseField>

    <ResponseField name="business_phones" type="array">
      Array of phone numbers (list of strings).
    </ResponseField>

    <ResponseField name="expand" type="object">
      Additional contact details to merge into the request body. See [https://docs.microsoft.com/en-us/graph/api/resources/contact](https://docs.microsoft.com/en-us/graph/api/resources/contact)
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "$defs": {
        "ContactSummary": {
          "additionalProperties": false,
          "properties": {
            "id": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Id"
            },
            "displayName": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Displayname"
            },
            "givenName": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Givenname"
            },
            "surname": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Surname"
            },
            "emailAddresses": {
              "items": {
                "additionalProperties": true,
                "type": "object"
              },
              "title": "Emailaddresses",
              "type": "array"
            },
            "businessPhones": {
              "items": {
                "type": "string"
              },
              "title": "Businessphones",
              "type": "array"
            }
          },
          "title": "ContactSummary",
          "type": "object"
        }
      },
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "contact": {
          "anyOf": [
            {
              "$ref": "#/$defs/ContactSummary"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "required": [
        "success"
      ],
      "title": "CreateContactOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="create_draft_email — Create a draft email.">
    ### Parameters

    <ResponseField name="recipients" type="array">
      Array of TO recipient email addresses (list of strings).
    </ResponseField>

    <ResponseField name="cc_recipients" type="array">
      Array of CC recipient email addresses (list of strings).
    </ResponseField>

    <ResponseField name="bcc_recipients" type="array">
      Array of BCC recipient email addresses (list of strings).
    </ResponseField>

    <ResponseField name="subject" type="string">
      Subject of the email.
    </ResponseField>

    <ResponseField name="content_type" type="string">
      Content type of the body. Valid values: text, html. (Default: `text`)
    </ResponseField>

    <ResponseField name="content" type="string">
      Body content of the email in text or HTML.
    </ResponseField>

    <ResponseField name="file_urls" type="array">
      Array of file URLs to fetch and attach to the message (list of strings).
    </ResponseField>

    <ResponseField name="expand" type="object">
      Additional Message resource fields merged into the request. See [https://docs.microsoft.com/en-us/graph/api/resources/message](https://docs.microsoft.com/en-us/graph/api/resources/message)
    </ResponseField>

    <ResponseField name="user_id" type="string">
      The User ID of a shared mailbox. If not provided, defaults to the authenticated user's mailbox.
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Id"
        },
        "subject": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Subject"
        },
        "isDraft": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Isdraft"
        },
        "webLink": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Weblink"
        }
      },
      "required": [
        "success"
      ],
      "title": "CreateDraftEmailOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="create_draft_reply — Create a draft reply to an email.">
    ### Parameters

    <ResponseField name="message_id" type="string" required>
      The identifier of the message to reply to.
    </ResponseField>

    <ResponseField name="comment" type="string">
      Content of the reply in text format.
    </ResponseField>

    <ResponseField name="recipients" type="array">
      Array of TO recipient email addresses to override on the draft (list of strings).
    </ResponseField>

    <ResponseField name="cc_recipients" type="array">
      Array of CC recipient email addresses (list of strings).
    </ResponseField>

    <ResponseField name="bcc_recipients" type="array">
      Array of BCC recipient email addresses (list of strings).
    </ResponseField>

    <ResponseField name="subject" type="string">
      Subject override for the reply.
    </ResponseField>

    <ResponseField name="file_urls" type="array">
      Array of file URLs to attach to the reply (list of strings).
    </ResponseField>

    <ResponseField name="expand" type="object">
      Additional Message resource fields merged into the message body.
    </ResponseField>

    <ResponseField name="user_id" type="string">
      The User ID of a shared mailbox.
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Id"
        },
        "subject": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Subject"
        },
        "isDraft": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Isdraft"
        }
      },
      "required": [
        "success"
      ],
      "title": "CreateDraftReplyOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="download_attachment — Downloads an attachment from a message and returns it as base64-encoded content with metadata.">
    ### Parameters

    <ResponseField name="message_id" type="string" required>
      The identifier of the message containing the attachment.
    </ResponseField>

    <ResponseField name="attachment_id" type="string" required>
      The identifier of the attachment to download.
    </ResponseField>

    <ResponseField name="user_id" type="string">
      The User ID of a shared mailbox.
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Name"
        },
        "content_type": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Content Type"
        },
        "size": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Size"
        },
        "content_bytes_base64": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Content Bytes Base64"
        }
      },
      "required": [
        "success"
      ],
      "title": "DownloadAttachmentOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="find_contacts — Finds contacts with the given search string.">
    ### Parameters

    <ResponseField name="search_string" type="string" required>
      Provide email address, given name, surname, or display name (case sensitive).
    </ResponseField>

    <ResponseField name="max_results" type="integer">
      The maximum number of results to return. (Default: `100`)
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "count": {
          "default": 0,
          "title": "Count",
          "type": "integer"
        },
        "contacts": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": "Contacts",
          "type": "array"
        }
      },
      "required": [
        "success"
      ],
      "title": "FindContactsOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="find_email — Search for an email in Microsoft Outlook. $search cannot be combined with $filter or $orderby.">
    ### Parameters

    <ResponseField name="search" type="string">
      Search query. Can use property syntax like "to:[example@example.com](mailto:example@example.com)" or "subject:example". Not for use with filter or order\_by.
    </ResponseField>

    <ResponseField name="filter" type="string">
      OData \$filter expression, e.g. contains(subject, 'meet for lunch?'). Not for use with search.
    </ResponseField>

    <ResponseField name="order_by" type="string">
      OData \$orderby expression, e.g. receivedDateTime desc. Not for use with search.
    </ResponseField>

    <ResponseField name="max_results" type="integer">
      Maximum number of messages to return. (Default: `100`)
    </ResponseField>

    <ResponseField name="include_attachments" type="boolean">
      If true, expands attachments on each returned message. (Default: `false`)
    </ResponseField>

    <ResponseField name="select" type="string">
      Comma-separated message property names to return (e.g. id,subject,from,receivedDateTime). Shrinks payload size.
    </ResponseField>

    <ResponseField name="user_id" type="string">
      The User ID of a shared mailbox.
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "count": {
          "default": 0,
          "title": "Count",
          "type": "integer"
        },
        "messages": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": "Messages",
          "type": "array"
        }
      },
      "required": [
        "success"
      ],
      "title": "FindEmailOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="find_shared_folder_email — Search for an email in a shared folder.">
    ### Parameters

    <ResponseField name="user_id" type="string" required>
      The user ID owning the shared folder.
    </ResponseField>

    <ResponseField name="shared_folder_id" type="string" required>
      The ID of the shared folder to search.
    </ResponseField>

    <ResponseField name="search" type="string">
      Search query. Not for use with filter or order\_by.
    </ResponseField>

    <ResponseField name="filter" type="string">
      OData \$filter expression.
    </ResponseField>

    <ResponseField name="order_by" type="string">
      OData \$orderby expression.
    </ResponseField>

    <ResponseField name="max_results" type="integer">
      Maximum number of messages to return. (Default: `100`)
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "count": {
          "default": 0,
          "title": "Count",
          "type": "integer"
        },
        "messages": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": "Messages",
          "type": "array"
        }
      },
      "required": [
        "success"
      ],
      "title": "FindSharedFolderEmailOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="get_current_user — Returns 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.">
    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Id"
        },
        "displayName": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Displayname"
        },
        "mail": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Mail"
        },
        "userPrincipalName": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Userprincipalname"
        }
      },
      "required": [
        "success"
      ],
      "title": "GetCurrentUserOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="get_message — Retrieve a single email message by its Microsoft Graph message ID.">
    ### Parameters

    <ResponseField name="message_id" type="string" required>
      The Microsoft Graph message ID.
    </ResponseField>

    <ResponseField name="include_attachments" type="boolean">
      If true, expands attachments on the returned message. (Default: `false`)
    </ResponseField>

    <ResponseField name="user_id" type="string">
      The User ID of a shared mailbox.
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "message": {
          "anyOf": [
            {
              "additionalProperties": true,
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Message"
        }
      },
      "required": [
        "success"
      ],
      "title": "GetMessageOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="list_contacts — Get a contact collection from the default contacts folder.">
    ### Parameters

    <ResponseField name="filter_address" type="string">
      If provided, only contacts with the given email address will be retrieved.
    </ResponseField>

    <ResponseField name="max_results" type="integer">
      Maximum number of contacts to return. (Default: `100`)
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "count": {
          "default": 0,
          "title": "Count",
          "type": "integer"
        },
        "contacts": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": "Contacts",
          "type": "array"
        }
      },
      "required": [
        "success"
      ],
      "title": "ListContactsOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="list_folders — Retrieves a list of mail folders in Microsoft Outlook.">
    ### Parameters

    <ResponseField name="max_results" type="integer">
      Maximum number of folders to return. (Default: `100`)
    </ResponseField>

    <ResponseField name="include_subfolders" type="boolean">
      If true, recursively include subfolders. (Default: `false`)
    </ResponseField>

    <ResponseField name="include_hidden_folders" type="boolean">
      If true, include hidden folders. (Default: `false`)
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "count": {
          "default": 0,
          "title": "Count",
          "type": "integer"
        },
        "folders": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": "Folders",
          "type": "array"
        }
      },
      "required": [
        "success"
      ],
      "title": "ListFoldersOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="list_important_mail — Get the most important mail from the user's Inbox (filters by high importance or flagged status).">
    ### Parameters

    <ResponseField name="max_results" type="integer">
      Maximum number of messages to return. (Default: `100`)
    </ResponseField>

    <ResponseField name="user_id" type="string">
      The User ID of a shared mailbox.
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "$defs": {
        "ImportantMailItem": {
          "additionalProperties": false,
          "properties": {
            "id": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Id"
            },
            "subject": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Subject"
            },
            "sender": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Sender"
            },
            "receivedDateTime": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Receiveddatetime"
            }
          },
          "title": "ImportantMailItem",
          "type": "object"
        }
      },
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "count": {
          "default": 0,
          "title": "Count",
          "type": "integer"
        },
        "data": {
          "items": {
            "$ref": "#/$defs/ImportantMailItem"
          },
          "title": "Data",
          "type": "array"
        }
      },
      "required": [
        "success"
      ],
      "title": "ListImportantMailOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="list_labels — Get all the labels/categories that have been defined for a user.">
    ### Parameters

    <ResponseField name="user_id" type="string">
      The User ID of a shared mailbox.
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "count": {
          "default": 0,
          "title": "Count",
          "type": "integer"
        },
        "labels": {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": "Labels",
          "type": "array"
        }
      },
      "required": [
        "success"
      ],
      "title": "ListLabelsOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="move_email_to_folder — Moves an email to the specified folder.">
    ### Parameters

    <ResponseField name="message_id" type="string" required>
      The identifier of the message to move.
    </ResponseField>

    <ResponseField name="folder_id" type="string" required>
      The identifier of the destination folder.
    </ResponseField>

    <ResponseField name="user_id" type="string">
      The User ID of a shared mailbox.
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Id"
        },
        "parentFolderId": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Parentfolderid"
        }
      },
      "required": [
        "success"
      ],
      "title": "MoveEmailToFolderOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="remove_label_from_email — Removes a label/category from an email.">
    ### Parameters

    <ResponseField name="message_id" type="string" required>
      The identifier of the message to update.
    </ResponseField>

    <ResponseField name="label" type="string" required>
      The name of the label/category to remove.
    </ResponseField>

    <ResponseField name="user_id" type="string">
      The User ID of a shared mailbox.
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Id"
        },
        "categories": {
          "items": {
            "type": "string"
          },
          "title": "Categories",
          "type": "array"
        }
      },
      "required": [
        "success"
      ],
      "title": "RemoveLabelFromEmailOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="reply_to_email — Reply to an email.">
    ### Parameters

    <ResponseField name="message_id" type="string" required>
      The identifier of the message to reply to.
    </ResponseField>

    <ResponseField name="comment" type="string">
      Content of the reply in text format.
    </ResponseField>

    <ResponseField name="recipients" type="array">
      Optional override for TO recipients (list of strings).
    </ResponseField>

    <ResponseField name="cc_recipients" type="array">
      CC recipient email addresses (list of strings).
    </ResponseField>

    <ResponseField name="bcc_recipients" type="array">
      BCC recipient email addresses (list of strings).
    </ResponseField>

    <ResponseField name="subject" type="string">
      Optional subject override.
    </ResponseField>

    <ResponseField name="file_urls" type="array">
      Array of file URLs to attach (list of strings).
    </ResponseField>

    <ResponseField name="expand" type="object">
      Additional Message resource fields merged into the reply body.
    </ResponseField>

    <ResponseField name="user_id" type="string">
      The User ID of a shared mailbox.
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "sent": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Sent"
        }
      },
      "required": [
        "success"
      ],
      "title": "ReplyToEmailOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="send_email — Send an email to one or multiple recipients.">
    ### Parameters

    <ResponseField name="recipients" type="array">
      TO recipient email addresses (list of strings).
    </ResponseField>

    <ResponseField name="cc_recipients" type="array">
      CC recipient email addresses (list of strings).
    </ResponseField>

    <ResponseField name="bcc_recipients" type="array">
      BCC recipient email addresses (list of strings).
    </ResponseField>

    <ResponseField name="subject" type="string">
      Subject of the email.
    </ResponseField>

    <ResponseField name="content_type" type="string">
      Content type of the body. Valid values: text, html. (Default: `text`)
    </ResponseField>

    <ResponseField name="content" type="string">
      Body content of the email.
    </ResponseField>

    <ResponseField name="file_urls" type="array">
      Array of file URLs to fetch and attach (list of strings).
    </ResponseField>

    <ResponseField name="expand" type="object">
      Additional Message resource fields merged into the request.
    </ResponseField>

    <ResponseField name="user_id" type="string">
      The User ID of a shared mailbox.
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "sent": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Sent"
        }
      },
      "required": [
        "success"
      ],
      "title": "SendEmailOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="update_contact — Update an existing contact.">
    ### Parameters

    <ResponseField name="contact_id" type="string" required>
      The ID of the contact to update.
    </ResponseField>

    <ResponseField name="given_name" type="string">
      Given name of the contact.
    </ResponseField>

    <ResponseField name="surname" type="string">
      Surname of the contact.
    </ResponseField>

    <ResponseField name="email_addresses" type="array">
      Replacement email addresses for the contact (list of strings).
    </ResponseField>

    <ResponseField name="business_phones" type="array">
      Replacement phone numbers (list of strings).
    </ResponseField>

    <ResponseField name="expand" type="object">
      Additional contact fields merged into the request body.
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "$defs": {
        "ContactSummary": {
          "additionalProperties": false,
          "properties": {
            "id": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Id"
            },
            "displayName": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Displayname"
            },
            "givenName": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Givenname"
            },
            "surname": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Surname"
            },
            "emailAddresses": {
              "items": {
                "additionalProperties": true,
                "type": "object"
              },
              "title": "Emailaddresses",
              "type": "array"
            },
            "businessPhones": {
              "items": {
                "type": "string"
              },
              "title": "Businessphones",
              "type": "array"
            }
          },
          "title": "ContactSummary",
          "type": "object"
        }
      },
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "contact": {
          "anyOf": [
            {
              "$ref": "#/$defs/ContactSummary"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "required": [
        "success"
      ],
      "title": "UpdateContactOutput",
      "type": "object"
    }
    ```
  </Accordion>
</AccordionGroup>

## Limits & Quotas

* Microsoft Graph throttles per-app and per-mailbox. Mail endpoints allow approximately 10,000 requests per 10 minutes per app per mailbox; consult Microsoft's throttling guidance for exact tiers.
* Search uses Microsoft Graph KQL semantics; combining `search` with `filter` or `order_by` is rejected by Microsoft Graph and short-circuited locally with a `success=False` error.
* Attachments are accepted as URLs only; the integration fetches each URL and base64-encodes the bytes for Microsoft Graph's `fileAttachment` payload. `download_attachment` returns base64-encoded bytes rather than writing files to disk.
* The `approve_workflow` action does not internally suspend a workflow; the caller must supply both `resume_url` and `cancel_url`. The action only sends the approval email.
* Error model: non-2xx responses are caught and returned as `success=False` + `error`; the calling agent can retry or surface the error.

## Related integrations

<CardGroup cols={3}>
  <Card title="Gmail" href="/integrations/tools/gmail" />

  <Card title="AgentMail" href="/integrations/tools/agentmail" />

  <Card title="Mailgun" href="/integrations/tools/mailgun" />
</CardGroup>

## Links

* [Microsoft Outlook](https://outlook.live.com)