# Outlook Mail

Connects an agent to a Microsoft Outlook mailbox via the Microsoft Graph API. The agent can monitor an inbox for incoming emails, reply automatically, or send proactive email notifications.

- **Supported agents:** Agentic Flow, Coworker
- **Route types:** Trigger, Conversation, Notification
- **Auth:** Microsoft OAuth SSO (delegated permissions)

## Route Overview

| Route | Direction | Use when |
| --- | --- | --- |
| Trigger | Inbound only | Monitoring the mailbox and firing the agent — no automatic reply |
| Conversation | Bidirectional | Monitoring the mailbox and sending agent replies back as emails |
| Notification | Outbound only | Agent sends emails proactively, without an inbound trigger |

## Before You Start

1. In the **Azure Portal** ([portal.azure.com](https://portal.azure.com)), go to **Azure Active Directory → App Registrations → New Registration**.
2. Name the app (e.g. `Neo-OutlookChannel`). Set supported account types to **Single tenant**.
3. Under **Authentication**, add a **Redirect URI** (type: Web): `https://<your-neo-domain>/api/channels/oauth/callback`. Enable **Access tokens** and **ID tokens** under Implicit grant.
4. Note the **Application (client) ID** and **Directory (tenant) ID** from the app overview.
5. Under **Certificates & Secrets**, create a **Client Secret**. Copy the value immediately.
6. Under **API Permissions**, add the following **Delegated** Microsoft Graph permissions: `Mail.Read`, `Mail.Send`, `User.Read`, `offline_access`.
7. Click **Grant admin consent for <tenant>**. All four permissions must show a green ✓ Granted status. Admin consent is required — individual users cannot self-consent on most enterprise tenants.

Your agent must be published with an active version.

## Configuration

**Credentials**

- **Client ID** — Application (client) ID from the Azure App Registration. Required.
- **Client Secret** — Client secret value. Required.
- **Tenant ID** — Directory (tenant) ID. Required.
- **Mailbox Email** — The email address of the mailbox to monitor or send from. Required.

After saving the credential, click **Login with Microsoft** to complete the OAuth SSO flow. Sign in with the mailbox account. On success, a green checkmark confirms the account is connected. Tokens are stored encrypted and refreshed automatically.

## Trigger Route Settings

- **Description** / **Purpose** — Optional notes on what the channel is for and when the agent should use it.
- **Triggering Timing (mins)** — How often Neo checks the mailbox for new emails. Default: 5. Minimum: 5. Maximum: 60.
- **Batch Size** — Maximum emails processed per poll cycle. Default: 10. Range: 1–50.
- **Mail Folder** — Which Outlook folder to monitor. Default: `inbox`.
- **Unread Emails Only** — When ON, only unread emails are processed. Default: ON.
- **From Email Filter** — Only process emails from this sender. Optional.
- **Subject Contains** / **Body Contains** — Only process emails whose subject or body contains these keywords. Optional.
- **Initial Message** — Prompt prefix prepended to the email content when triggering the agent. Optional.

The Trigger route starts the agent; it does not reply to the email.

## Conversation Route Settings

- **Description** / **Purpose** — Optional.
- **Polling Interval (mins)** — How often Neo checks the mailbox. Default: 5. Minimum: 5. Maximum: 60.
- **Batch Size**, **Mail Folder**, **Unread Emails Only**, **From Email Filter**, **Subject Contains**, **Body Contains** — As for the Trigger route.
- **Process Full Thread** — Give the agent the whole email thread, not only the latest message. Default: ON.
- **Reply All** — Reply to all recipients instead of only the sender. Default: ON.

## Notification Route Settings

- **Description** / **Purpose** — Optional.
- **Default Recipients** / **Default CC** — Addresses that always receive notifications. Optional.
- **Reply All** — When replying to an inbound email, reply to all recipients instead of only the sender. Default: ON.
- **Default Subject Prefix** — Text added to the start of each subject line. Optional.
- **Max Retry Attempts** — Retries if sending fails. Default: 3. Range: 0–10.
- **Retry Delay (seconds)** — Delay between retries. Default: 60. Range: 10–600.

## Output Node (Agentic Flow)

For Conversation and Notification routes, select the **Output** node in the flow and turn on **Channel Delivery**. Configure the `delivery_targets` table: select the Outlook route, set the event type (`email` for new emails, `email_reply` for threaded replies), recipients, and invocation mode.

See [Component Types](../9_agentic_flow_builder/building_blocks.html) for details on the Output node.

## Troubleshooting

- **Login with Microsoft button does nothing** — Save the credential first. Allow browser popups for your Neo domain. Verify the redirect URI in Azure matches your domain exactly.
- **Emails not being picked up** — Check the channel toggle is ON and the agent is published. Verify the correct mailbox email is set. Check that the `Unread Emails Only` filter is not excluding already-read emails.
- **Agent reply not sent** — Confirm the flow’s Output node has Channel Delivery turned on.
- **“Need admin approval” error during SSO** — A Tenant Administrator must grant admin consent in Azure Portal → App Registrations → API Permissions before non-admin users can complete the login.