This guide explains how to set up the EWS Outlook connector to ingest emails and attachments from Exchange Web Services (EWS) online archives and server-side folders. This connector requires a Bring Your Own (BYO) OAuth configuration.

## 1. Create an OAuth Connector

Before you can set up the EWS Outlook data source, you need to configure a Microsoft OAuth connector in Airia. This involves registering an application in Azure and then linking it in Airia.

### Register Your Application in Azure

1.  **Register a Microsoft Application**:
    *   Go to the [Azure portal](https://portal.azure.com/) and register a new application.
    *   Configure the application with the redirect URL address provided by Airia. This URL is crucial for the OAuth flow.

2.  **Add API Permissions**:
    *   In your Azure app registration, navigate to **API permissions**.
    *   Add at least the following API permission scopes:
        *   `EWS.AccessAsUser.All` (Delegated permission)
        *   `offline_access` (Delegated permission)
        *   `openid` (Delegated permission)
        *   `profile` (Delegated permission)
    *   Click **Grant admin consent** for your tenant.
    *   You can add additional scopes if you plan to use this OAuth connector for other data sources or tools.
    *   From the app's **Overview** page, save the **Application (client) ID**.
    *   In the app's **Certificates & secrets** section, create a new client secret and save its **Value**.

### Configure the OAuth Connector in Airia

1.  Navigate to **Settings** > **OAuth Connectors** in the Airia platform.
2.  From the **Available** tab, select the **Microsoft** card.
3.  Enter the **Client ID** and **Client Secret** obtained from your Azure application.
4.  In the **Scopes** section, select the exact same scopes you configured in your Azure app:
    *   `EWS.AccessAsUser.All`
    *   `offline_access`
    *   `openid`
    *   `profile`
5.  Click **Create**.

> 💡 Note: Ensure the scopes selected in Airia precisely match those configured in your Azure application to prevent authentication errors.

## 2. Connect Your EWS Outlook Data Source

Once your OAuth connector is set up, you can proceed to create your EWS Outlook data source.

1.  Navigate to **Data Sources** in the Airia platform.
2.  Browse the available connectors library and select the **EWS Outlook** card.

### Configure Data Source Details

1.  Provide a meaningful **Name** for your data source (e.g., `My Outlook Emails`).
2.  Optionally, add a **Description**.
3.  **Select a Scope**: Choose which projects can access this data source.
4.  **Select an OAuth Connector**: From the dropdown, select the Microsoft OAuth connector you created in the previous section.

### Add Credentials

1.  If this is your first time using this connector, select **Add new credential**.
2.  Provide a **Name** for the credential.
3.  List the required **Scopes** for EWS to function. You can add more if you intend to use this credential for other data sources or tools.
4.  Click **Authenticate**. Complete the OAuth flow by logging in with the user whose mailbox you want to access.

### Select Mailbox Type and Ingestion Settings

1.  **Select Mailbox Type**:
    *   Choose between **Personal Mailbox** or **Shared Mailbox**.
    *   If you select **Shared Mailbox**, you must specify the email address of the shared mailbox.
2.  **Ingestion Settings**: (Optional) Configure preferred ingestion settings. If left blank, Airia will apply default settings.
3.  Click **Next** to proceed.

### Select Folders and Start Ingestion

1.  On the next screen, choose the specific folders from the Inbox that you wish to ingest.
2.  Click **Done** to create the data source and initiate the ingestion process.

## 3. Use Your EWS Outlook Data

After ingestion is complete, you can use your EWS Outlook data source in two primary ways:

### Perform Semantic Search

To perform semantic search on the content of your emails and their attachments:

1.  Drag and drop your **EWS Outlook** data source onto the canvas.
2.  Add the data source to an **Agent**.

This setup allows you to retrieve information based on the content of email bodies and attachments.

### Query Email Metadata

If you need to query emails based on their metadata (e.g., subject, sender, receiver), this information is stored in a dedicated Knowledge Graph for your data source. You can access this graph using the Airia native Query Graph DB tool.

1.  Navigate to the **Tools** section in Airia.
2.  Click **Add new tool**.
3.  From the library, select the **Query Graph DB** tool.
4.  In the **Select an existing graph** dropdown, choose the name of your EWS Outlook data source.
5.  Click **Create**.
6.  Add the newly created **Query Graph DB** tool to your **Agent**.

> 💡 Note: Ensure that your EWS Outlook data source, the Agent you're using, and the Query Graph DB Tool are all created within the same project.
