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
* **Route types:** Trigger, Conversation, Notification
* **Auth:** Microsoft OAuth SSO (delegated permissions)

Route Overview
--------------

.. list-table::
   :widths: 20 20 60
   :header-rows: 1

   * - 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. For Conversation and Notification routes, the Channel Gateway MCP must be enabled:

* **Global:** Admin Panel → MCP Servers → Channel Gateway → Enable and Deploy
* **Workspace:** Workspace Settings → MCP → Channel Gateway → toggle ON

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

* **Polling Interval (mins)** — How often Neo checks the mailbox for new emails. Default: 5. Range: 1–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** — Only process emails whose subject contains these keywords (comma-separated tags). Optional.
* **Initial Message** — Prompt prefix prepended to the email content when triggering the agent. Optional.

Conversation Route Settings
----------------------------

Same as Trigger, plus the agent replies to each email automatically via the Channel Output node.

Notification Route Settings
----------------------------

* **Max Retry Attempts** — Retries if sending fails. Default: 3. Range: 0–10.
* **Retry Delay (seconds)** — Delay between retries. Default: 60. Range: 10–600.

Channel Output Node (Agentic Flow)
-----------------------------------

For Conversation and Notification routes, add a **Channel Output** node to the flow and enable **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 :doc:`/9_agentic_flow_builder/building_blocks` for details on the Channel 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 Channel Output node is in the flow with Channel Delivery enabled. Verify Channel Gateway MCP is enabled at both levels.
* **"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.