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

# Outlook

> Configure the mAItion Outlook connector to ingest emails from a Microsoft 365 mailbox into the knowledge base.

Use the Outlook Connector to ingest emails from a Microsoft 365 mailbox via the [Microsoft Graph API](https://learn.microsoft.com/en-us/graph/overview) into the mAItion knowledge base.

## What It Does

* fetches emails from a configurable mail folder in a Microsoft 365 mailbox
* authenticates directly against Microsoft Entra ID using the OAuth2 client credentials flow (app-only, non-interactive)
* converts HTML email bodies to Markdown for indexing
* runs ingestion on configurable schedules

## Authentication

Only the client credentials flow (app-only) is supported. This requires:

* An Azure app registration that can read the target mailbox, using one of the two options below.
* A **Microsoft 365 / Entra ID work or school account** mailbox. Personal Microsoft accounts are not supported — client credentials flow is not available for them.

### Mailbox Access Options

> [!WARNING]
>
> The Entra ID `Mail.Read` **application** permission is unscoped: it grants access to **every mailbox in the tenant**. The `user_email` setting only selects which mailbox this connector queries. It does not limit what the app registration can reach.

| Option | Setup | Reach |
| - | - | - |
| Unscoped (simple) | Grant the `Mail.Read` application permission in Entra ID and give admin consent | All mailboxes in the tenant |
| Scoped (recommended) | Assign the **Application Mail.Read** role in Exchange Online with a management scope that covers only the mailboxes you need | Only the scoped mailboxes |

To use the scoped option, follow [RBAC for Applications in Exchange Online](https://learn.microsoft.com/en-us/exchange/permissions-exo/application-rbac): create a management scope, register the app's service principal in Exchange with `New-ServicePrincipal`, then assign the role with `New-ManagementRoleAssignment -App <service-principal-id> -Role "Application Mail.Read" -CustomResourceScope <scope>`.

> [!WARNING]
>
> After you assign the scoped role, **remove the unscoped `Mail.Read` grant from Entra ID**. The two grants combine as a union, so if the Entra ID grant stays, the app keeps access to every mailbox and the scope has no effect.

## Required Environment Variables

Set these in `.env.rag`:

* `OUTLOOK1_CLIENT_ID`: Azure app registration client ID
* `OUTLOOK1_CLIENT_SECRET`: Azure app registration client secret
* `OUTLOOK1_TENANT_ID`: Azure tenant / directory ID
* `OUTLOOK1_USER_EMAIL`: mailbox owner email address (example: `user@company.onmicrosoft.com`)
* `OUTLOOK1_SCHEDULES`: ingestion interval in seconds (default is `3600`)

## `config.yaml` Example

```yaml theme={null}
sources:
  - type: "outlook"
    name: "outlook1"
    enabled: true  # optional, default: true
    config:
      client_id: "${OUTLOOK1_CLIENT_ID}"
      client_secret: "${OUTLOOK1_CLIENT_SECRET}"
      tenant_id: "${OUTLOOK1_TENANT_ID}"
      user_email: "${OUTLOOK1_USER_EMAIL}"
      folder: "Inbox"           # optional, default Inbox; custom display names are resolved automatically
      num_mails: 100            # optional, default 10
      html_to_text: true        # optional, default true; set to false to keep raw HTML email bodies
      schedules: "${OUTLOOK1_SCHEDULES}"
```

## `.env.rag` Example

```dotenv theme={null}
OUTLOOK1_CLIENT_ID=your-azure-app-client-id
OUTLOOK1_CLIENT_SECRET=your-azure-app-client-secret
OUTLOOK1_TENANT_ID=your-azure-tenant-id
OUTLOOK1_USER_EMAIL=user@company.onmicrosoft.com
OUTLOOK1_SCHEDULES=3600
```

## Configuration Reference

| Field | Required | Default | Description |
| - | - | - | - |
| `enabled` | no | `true` | Set to `false` to skip this source entirely |
| `client_id` | yes | — | Azure app registration client ID |
| `client_secret` | yes | — | Azure app registration client secret |
| `tenant_id` | yes | — | Azure tenant / directory ID |
| `user_email` | yes | — | Mailbox owner email address |
| `folder` | no | `Inbox` | Mail folder to ingest. Well-known folder names (e.g. `Inbox`, `SentItems`) are used directly; custom display names are resolved automatically |
| `num_mails` | no | `10` | Maximum number of emails to fetch |
| `html_to_text` | no | `true` | Convert HTML email bodies to Markdown; set to `false` to keep raw HTML |
| `schedules` | no | `3600` | Ingestion interval in seconds |

## Multiple Outlook Sources

Add more `sources` entries (`outlook2`, `outlook3`, etc) with separate env vars per source.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.