Skip to content

docs(outlook): expand Mail & Calendar tool reference #83

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
matthieuhaguen merged 3 commits into from
Aug 27, 2026
Merged

docs(outlook): expand Mail & Calendar tool reference #83

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b888a39
Update Microsoft Outlook tool docs: full tool list, scopes, troublesh…
matthieuhaguen Aug 26, 2026
94c5390
docs(outlook): align page title with sibling tool pages, complete las…
axel-ext-dust Aug 27, 2026
1fee5d5
docs(outlook): simplify overview/usage, restore admin-consent trouble…
Aug 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
129 changes: 99 additions & 30 deletions docs/user-documentation/agents/tools/microsoft-outlook.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,59 +1,128 @@
---
title: "Microsoft Outlook (Mail, Calendar)"
title: "Microsoft Outlook"
---


## Overview

Outlook tools let you add to your agent the capability to interact with your email inbox on Outlook. This provides the ability to read emails, as well as create and delete drafts.
Outlook tools let your agents work with your Microsoft 365 mailbox and calendar.
Agents can read messages and their full body, browse the folder hierarchy,
download attachments, create and delete drafts, send mail, move messages into
folders, manage contacts, and create or update calendar events.

This document provides general information about our Outlook tool (available tools, setup, and authentication).
This document covers the available tools, setup, authentication, and the scopes
Dust requests.

<Info>
**This tool uses personal credentials.** This tool interacts with Outlook
using the user's account: it adapts to each user.
**This tool uses personal credentials.** Each user authenticates with their
own Microsoft account, so an agent only ever sees what that user can see.
Outlook Mail can also be installed with workspace credentials for
platform-level automations; Outlook Calendar is personal-credentials only.
</Info>

## Setting up the Connection
## Admin: Setup in Dust

The setup process **requires a Microsoft Entra ID admin** ('privileged role
administrator' or 'application administrator') who is also a Dust admin. This
ensures full access to the necessary permissions.

The setup process **requires an Outlook Admin** (Microsoft Entra ID 'privileged role administrator' or 'application administrator') who is also a Dust Admin. This ensures full access to the necessary permissions.
1. Under **Spaces → Tools**, select `Add Tools`, then select `Outlook`.
2. Review the permissions. Each tool action can be set to one of four stake
levels: high (always ask for confirmation), medium (let users save a
confirmation for a specific input), low (users can disable confirmations
entirely), or never ask (runs automatically) from the "Available tools"
settings.
3. On the first connection, tick **Consent on behalf of your organization**.

1. Under **Spaces → Tools**, select `Add Tools`. Then select `Outlook`.
2. A modal will show to allow you to allow Dust to access your Outlook data. On the first connection, tick the box **Consent on behalf of your organization**.
Once the tool is set up, **each user must connect their own Microsoft account**
the first time an agent uses an Outlook tool on their behalf. Dust prompts them
automatically.

## Adding Outlook Tools to agents
## Usage

After admin set-up, Outlook tools can simply be added to an agent by selecting them in the agent builder. They require no configuration. Note that when connecting a tool, you can define the provided tools as high stake or low stake.
After admin setup, the Outlook tool can be added to an agent by selecting it
from the agent builder. They require no additional configuration.

## Available Tools

### Outlook Mail

| Tool | Description |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Get Messages | Get messages from Outlook inbox. Supports search queries to filter messages. |
| Get Drafts | Get all draft emails from Outlook. |
| Create Draft | Create a new email draft in Outlook. The draft will be saved in the user's Outlook account and can be reviewed and sent later. The draft will include proper email headers and formatting. |
| Delete Draft | Delete a draft email from Outlook. |
| Create Reply Draft | Create a reply draft to an existing email in Outlook. The draft will be saved in the user's Outlook account and can be reviewed and sent later. The reply will be properly formatted with the original message quoted. The draft will include proper email headers and threading information. |
| Tool | Write | Description |
| --- | --- | --- |
| Get Messages | | Get message metadata and previews (subject, sender, date, and a ~255 character body preview, not the full body). Supports search queries and a folder path. |
| Get Message Body | | Get the full body of a single message. Supports chunked reads for large emails. |
| List Folders | | List mail folders. Returns the children of a given folder path, or top-level folders. Use it to discover the hierarchy before filtering messages by folder. |
| List Attachments | | List attachments on a message (metadata only: id, name, content type, size). |
| Get Attachment | | Retrieve a single attachment by ID. Works for files above 4MB via a dedicated download endpoint. |
| Get Attachments | | Retrieve all attachments of a message at once. |
| Get Drafts | | Get draft emails. |
| Create Draft | ✓ | Create a new draft, or a reply draft to an existing message. Saved in the user's account for later review. |
| Delete Draft | ✓ | Delete a draft email. |
| Send Mail | ✓ | Send an email immediately, without creating a draft first. |
| Move Messages | ✓ | Move one or more messages to a destination folder, given as a path of folder names from the top level (for example `["Archive", "2026", "Receipts"]`). Folders that do not exist along the path are created automatically. Note that Microsoft Graph assigns a new message ID after a move. |
| Get Contacts | | Get contacts. Supports search queries. |
| Create Contact | ✓ | Create a new contact. |
| Update Contact | ✓ | Update an existing contact. |

### Outlook Calendar

| Tool | Description |
| ------------------ | ------------------------------------------------------------------------------------------------ |
| List Calendars | List all calendars accessible by the user in Outlook. |
| List Events | List or search events from an Outlook Calendar. Supports filtering and searching. |
| Get Event | Get a single event from an Outlook Calendar by event ID. |
| Create Event | Create a new event in an Outlook Calendar. |
| Update Event | Update an existing event in an Outlook Calendar. |
| Delete Event | Delete an event from an Outlook Calendar. |
| Check Availability | Check the calendar availability of specific people for a given time slot using Outlook Calendar. |
| Tool | Write | Description |
| --- | --- | --- |
| Get User Timezone | | Get the user's timezone from their mailbox settings. Called before other calendar operations for correct timezone handling. |
| List Calendars | | List all calendars accessible by the user. |
| List Events | | List or search events. Supports filtering and searching. |
| Get Event | | Get a single event by ID. |
| Create Event | ✓ | Create a new event, with attendees, location, and online meeting options. |
| Update Event | ✓ | Update an existing event. |
| Delete Event | ✓ | Delete an event. |
| Check Availability | | Compute combined free/busy availability across several participants over a date range. |
| Check Self Availability | | Check whether the signed-in user is free during a time slot. An event blocks if its status is busy, tentative, out of office, or working elsewhere. |

## Permissions needed

If your users struggle with approval requirements, you can go in the Azure Admin portal and grant permissions at admin level.
Dust requests **delegated** permissions, so a user can never do more through
Dust than they can do in Outlook directly.

### Outlook Mail

| Scope | Required for |
| --- | --- |
| `Mail.ReadWrite` | Read and modify mail, including moving messages between folders |
| `Mail.Send` | Send mail on behalf of the signed-in user |
| `User.Read` | Read basic profile information |
| `SensitivityLabel.Read` | Read sensitivity labels applied to messages |
| `offline_access` | Maintain access without re-authentication |
| `Mail.ReadWrite.Shared` | Access shared and delegated mailboxes (optional) |
| `Mail.Send.Shared` | Send from shared and delegated mailboxes (optional) |
| `Contacts.ReadWrite` | Read and modify contacts (optional) |
| `Contacts.ReadWrite.Shared` | Access shared contact folders (optional) |

<Note>
There is no read-only Outlook Mail setup. `Mail.ReadWrite` and `Mail.Send` are
required for the tool to function, and the shared variants imply them. Control
what agents are allowed to do with the per-tool stake settings in the agent
builder rather than with scopes: leave Send Mail as high stake, or simply do
not add it to the agent.
</Note>

### Outlook Calendar

| Scope | Required for |
| --- | --- |
| `Calendars.ReadWrite` | Read and modify calendar events |
| `User.Read` | Read basic profile information |
| `offline_access` | Maintain access without re-authentication |
| `Calendars.ReadWrite.Shared` | Access shared and delegated calendars (optional) |
| `MailboxSettings.Read` | Read timezone and working hours (optional) |

### Permissions needed

If your users struggle with approval requirements, you can go in the Azure
Admin portal and grant permissions at admin level.

For that go to the Azure Admin Portal, then **Enterprise applications** (you can follow this [link](https://portal.azure.com/#view/Microsoft_AAD_IAM/StartboardApplicationsMenuBlade/~/AppAppsPreview) instead), then **Dust - Tools**, then **Permissions** and click the **Grant admin consent** blue button.
For that go to the Azure Admin Portal, then **Enterprise applications** (you
can follow this [link](https://portal.azure.com/#view/Microsoft_AAD_IAM/StartboardApplicationsMenuBlade/~/AppAppsPreview)
instead), then **Dust - Tools**, then **Permissions** and click the **Grant
admin consent** blue button.

**Still not working?**

Expand Down