Outlook

Use the Outlook Connector to ingest emails from a Microsoft 365 mailbox via the Microsoft Graph API 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

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: 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>.

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

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

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.

Getting started

Features

Connectors

Tools

Configuration

What It Does

Authentication

Mailbox Access Options

Required Environment Variables

`config.yaml` Example

`.env.rag` Example

Configuration Reference

Multiple Outlook Sources

​What It Does

​Authentication

​Mailbox Access Options

​Required Environment Variables

​config.yaml Example

​.env.rag Example

​Configuration Reference

​Multiple Outlook Sources

What It Does

Authentication

Mailbox Access Options

Required Environment Variables

`config.yaml` Example

`.env.rag` Example

Configuration Reference

Multiple Outlook Sources