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

# Microsoft

> Authorize Microsoft and connect personal or shared Microsoft mailboxes to Stuut.

Microsoft requires an organization administrator to grant consent before Microsoft mailboxes can be connected. Authorization does not automatically connect any mailboxes.

## Authorize Microsoft

Organization authorization grants Stuut access to work with your Microsoft tenant and discover shared mailboxes. It is completed once by a Microsoft administrator.

### Before you begin

You will need:

* A Stuut organization administrator account
* A Microsoft administrator account permitted to grant tenant-wide consent

### Authorize your organization

1. Open **Settings → Mail** in the Stuut dashboard.
2. Find Microsoft in the **Providers** section.
3. Enable Microsoft if it is not already enabled.
4. Click **Authorize**.
5. Sign into Microsoft with an organization administrator account.
6. Review and approve the requested permissions.
7. Return to Stuut and confirm that Microsoft appears as **Authorized**.

### Application permissions

| Permission             | Purpose                                                  | What Stuut accesses                                                                                                                                                                                  |
| ---------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Mail.Read`            | Ingest inbound emails to match against open invoices.    | Only mail from shared mailboxes explicitly connected in Stuut. Personal mailboxes use a separate user authorization flow.                                                                            |
| `Mail.ReadWrite`       | Manage read/unread state and message categories.         | Message state and metadata in explicitly connected shared mailboxes. Microsoft requires this broader permission because it does not offer a narrower application permission for updating read state. |
| `Mail.Send`            | Send outbound collection emails from the shared address. | Sends only through shared mailboxes explicitly connected and selected as an email sender in Stuut.                                                                                                   |
| `User.Read.All`        | Identify which tenant mailboxes are shared.              | Requests only each account's `id`, `mail`, and `displayName`. Stuut does not query passwords or group memberships.                                                                                   |
| `MailboxSettings.Read` | Distinguish shared vs. personal mailboxes.               | Requests only the `userPurpose` mailbox-setting property.                                                                                                                                            |
| `Application.Read.All` | Verify Stuut's own consent status (health check).        | Reads Stuut's service principal, its assigned application roles and consent grants, and Microsoft Graph permission metadata. The health check does not modify applications or permissions.           |

<Note>
  Microsoft application permissions are tenant-wide by default. Stuut uses them only for connected shared mailboxes.
</Note>

## Add mailboxes

After Microsoft is authorized, each shared or personal mailbox must be added to Stuut individually.

### Shared mailboxes

Shared Microsoft mailboxes use the organization-approved application permissions described above. No one needs to sign in as the shared mailbox or provide its password.

Each shared mailbox must be selected and connected individually.

#### Add a shared mailbox

1. Open **Settings → Mail**.
2. Click **Add mailbox**.
3. Select **Shared mailbox**.
4. Select **Microsoft**.
5. Choose a shared mailbox discovered in your Microsoft tenant.
6. Enter an optional display name.
7. Choose whether to use it as a centralized inbox.
8. Click **Connect mailbox**.

### Personal mailboxes

Each user must sign into Microsoft and authorize their own mailbox. Personal mailboxes use delegated permissions associated with the signed-in user.

#### Delegated permissions

These delegated permissions apply to the signed-in account and any shared mailboxes that account is already permitted to access. Connecting one personal mailbox does not automatically connect other mailboxes in the organization.

| Permission              | Purpose                                                        | What Stuut accesses                                                                                   |
| ----------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `offline_access`        | Keep the mailbox connected without requiring repeated sign-in. | Allows Nylas to refresh the mailbox connection. Stuut does not receive or store the mailbox password. |
| `openid`                | Sign the user in securely with Microsoft.                      | The identity information needed to complete secure sign-in.                                           |
| `profile`               | Read basic profile information for the signed-in user.         | Basic account details returned during Microsoft authentication.                                       |
| `User.Read`             | Identify the signed-in user and their email address.           | The connected user's basic profile and email address.                                                 |
| `Mail.Read`             | Read messages in the user's mailbox.                           | Messages and attachments in the connected mailbox.                                                    |
| `Mail.ReadWrite`        | Manage messages and synchronize message state.                 | Messages and metadata in the connected mailbox, including read and unread state.                      |
| `Mail.Send`             | Send messages from the user's mailbox.                         | Sends only through the mailbox connected and selected in Stuut.                                       |
| `Mail.Read.Shared`      | Read messages in shared mailboxes the user can access.         | Mail in shared mailboxes for which the signed-in user already has Microsoft access.                   |
| `Mail.ReadWrite.Shared` | Manage messages in shared mailboxes the user can access.       | Messages and metadata in shared mailboxes for which the user already has Microsoft access.            |
| `Mail.Send.Shared`      | Send from shared mailboxes the user is authorized to use.      | Sends only when the signed-in user already has the required Microsoft send permission.                |

<Note>
  Connecting a personal mailbox does not give Stuut organization-wide access. The connection uses the permissions and mailbox access already assigned to the signed-in Microsoft user.
</Note>

#### Add a personal mailbox

1. Open **Settings → Mail**.
2. Click **Add mailbox**.
3. Select **Personal mailbox**.
4. Select Microsoft if prompted.
5. Sign into the Microsoft account that owns the mailbox.
6. Review and approve the requested access.
7. Return to Stuut and confirm that the mailbox appears as connected.

## Disconnect or revoke access

To stop using one mailbox, disconnect it from **Settings → Mail**. Existing communication history will be preserved.

An organization administrator can revoke Microsoft access through the organization's Microsoft Entra settings. Revoking organization access may affect every Microsoft mailbox connected through that authorization.

Questions? Contact your Stuut team.