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

# Microsoft Outlook as a data source

> Bring emails, attachments and mail folders from Microsoft Outlook to Nekt.

Microsoft Outlook is Microsoft's email service, used both with personal Outlook.com accounts and with Microsoft 365 work accounts (Exchange Online). This connector reads the mailbox of the signed-in account through the Microsoft Graph API, so you can analyze emails from every folder, the folder structure and, optionally, keep the email attachments as files in a Nekt volume.

## Configuring Microsoft Outlook as a Source

In the [Sources](https://app.nekt.ai/sources) tab, click on the "Add source" button located on the top right of your screen. Then, select the Microsoft Outlook option from the list of connectors.

Click **Next** and you'll be prompted to add your access.

### 1. Add account access

Click the **Microsoft Authentication** button and sign in with the Microsoft account whose mailbox you want to sync. Microsoft asks you to allow Nekt to read your mail and your basic profile. Nekt only reads data: it never sends, changes or deletes emails.

Both Microsoft 365 work or school accounts and personal Outlook.com accounts are supported.

> [!NOTE]
>
> Reading mail is a permission that many organizations only let an administrator approve. If Microsoft shows a "Need admin approval" screen, ask your Microsoft 365 administrator to grant consent to Nekt for your organization, then authorize again.

The following configurations are available:

* **Initial sync date**: Only emails received or changed on or after this date are synced.

* **Include SPAM and Trash**: (Default: `false`) When enabled, emails in the **Junk Email** and **Deleted Items** folders (and their subfolders) are also synced. When disabled, they are left out.

* **Enable email attachments stream**: (Default: `false`) When enabled, the **Email Attachments** stream downloads the file attachments of every synced email and uploads them to a Nekt volume. This makes extractions significantly slower and heavier: each attachment is downloaded from Outlook and re-uploaded to Nekt. Only enable this if you need the email files stored in a Nekt volume. If you turn this option on for a source that already exists, the attachments of emails synced before only arrive after a **Full Sync**.

* **Attachments Volume**: Nekt volume to upload email attachments to. Required when the email attachments stream is enabled.

Once you're done, click **Next**.

### 2. Select streams

Choose which data streams you want to sync. For faster extractions, select only the streams that are relevant to your analysis.

> Tip: The stream can be found more easily by typing its name.

Select the streams and click **Next**.

### 3. Configure data streams

Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a folder to organize it inside the layer, a name for each table (which will effectively contain the fetched data) and the type of sync.

* **Layer**: choose between the existing layers on your catalog. This is where you will find your new extracted tables as the extraction runs successfully.
* **Folder**: a folder can be created inside the selected layer to group all tables being created from this new data source.
* **Table name**: we suggest a name, but feel free to customize it. You have the option to add a **prefix** to all tables at once and make this process faster!
* **Sync Type**: you can choose between INCREMENTAL and FULL\_TABLE.
  * **Incremental** (recommended for **Email** and **Email Attachments**): each run brings the emails received or changed since the previous run (read, flagged, categorized or moved to another folder), based on `last_modified_date_time`.
  * **Full table** (used by **Mail Folder**): each run replaces the table with the current folder tree.

> [!WARNING]
>
> Keep **Email Attachments** on Incremental. As Full table under an incremental **Email**, each run would replace the attachments table with only the files of the emails read in that run.

Once you are done configuring, click **Next**.

### 4. Configure data source

Describe your data source for easy identification within your organization, not exceeding 140 characters.

To define your [Trigger](https://docs.nekt.com/runs/scheduling-and-triggers.md), consider how often you want data to be extracted from this source. This decision usually depends on how frequently you need the new table data updated (every day, once a week, or only at specific times).

Optionally, you can define some additional settings:

* Configure Delta Log Retention and determine for how long we should store old states of this table as it gets updated. Read more about this resource [here](https://docs.nekt.com/get-started/core-concepts/resource-control).
* Determine when to execute an **Additional [Full Sync](https://docs.nekt.com/get-started/core-concepts/types-of-sync#additional-full-sync)**. This will complement the incremental data extractions, ensuring that your data is completely synchronized with your source every once in a while.

Once you are ready, click **Next** to finalize the setup.

### 5. Check your new source

You can view your new source on the [Sources](https://app.nekt.ai/sources) page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.

> [!WARNING]
>
> For you to be able to see it on your [Catalog](https://app.nekt.ai/catalog), you need at least one successful source run.

# Streams and Fields

Below you'll find all available data streams from Microsoft Outlook and their corresponding fields. Every stream needs the permission to read mail that you grant when you authorize the source.

> [accordion] Email
>
> Every email of the mailbox, from all folders (Inbox, Sent Items, Drafts, Archive, your own folders and subfolders). Junk Email and Deleted Items are included only when **Include SPAM and Trash** is on. Sync is incremental on **`last_modified_date_time`**: an email that is read, flagged, categorized or moved to another folder comes again with its new values.
>
> **Key fields:**
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | String | Unique identifier of the email. It does not change when the email moves to another folder. |
> | `created_date_time` | DateTime | When the email was created in the mailbox (UTC). |
> | `last_modified_date_time` | DateTime | When the email was last changed, in UTC. Used as the incremental replication key. |
> | `received_date_time` | DateTime | When the email was received (UTC). |
> | `sent_date_time` | DateTime | When the email was sent (UTC). |
> | `change_key` | String | Version of the email; changes whenever the email changes. |
> | `categories` | Array | Outlook categories applied to the email. |
> | `has_attachments` | Boolean | Whether the email has attachments. Outlook does not count inline attachments (such as images in the body) here. |
> | `internet_message_id` | String | Message-ID header of the email. |
> | `subject` | String | Subject of the email. |
> | `body_preview` | String | First 255 characters of the body, as plain text. |
> | `body_content_type` | String | Format of `body_content`: `html` or `text`. |
> | `body_content` | String | Full body of the email (HTML for most emails). |
> | `importance` | String | Importance: `low`, `normal` or `high`. |
> | `parent_folder_id` | String | Folder that holds the email (see **Mail Folder**). |
> | `conversation_id` | String | Conversation (thread) the email belongs to. |
> | `conversation_index` | String | Position of the email within its conversation. |
> | `is_delivery_receipt_requested` | Boolean | Whether a delivery receipt was requested. |
> | `is_read_receipt_requested` | Boolean | Whether a read receipt was requested. |
> | `is_read` | Boolean | Whether the email was read. |
> | `is_draft` | Boolean | Whether the email is a draft (not sent yet). |
> | `web_link` | String | Link that opens the email in Outlook on the web. |
> | `inference_classification` | String | Focused Inbox classification: `focused` or `other`. |
> | `sender_name` | String | Display name of the account that sent the email. |
> | `sender_address` | String | Email address of the account that sent the email. |
> | `from_name` | String | Display name of the mailbox the email is from. |
> | `from_address` | String | Email address of the mailbox the email is from. |
> | `to_recipients` | String | To recipients, as a JSON array of objects with name and address. |
> | `cc_recipients` | String | Cc recipients, as a JSON array of objects with name and address. |
> | `bcc_recipients` | String | Bcc recipients, as a JSON array of objects with name and address. |
> | `reply_to` | String | Reply-To addresses, as a JSON array of objects with name and address. |
> | `flag_status` | String | Follow-up flag status: `notFlagged`, `flagged` or `complete`. |
> | `flag` | String | Follow-up flag with its start, due and completion dates, as a JSON object. |
> | `internet_message_headers` | String | Internet message headers, as a JSON array of objects with name and value. |

> [accordion] Email Attachments
>
> Downloads the file attachments of the synced emails and uploads them to a Nekt volume, with one row per file. This stream only runs when **Enable email attachments stream** is on and a volume is selected; if the table is selected while the option is off, the run reports this table as failed and asks you to turn the option on or deselect it.
>
> * Inline attachments (for example, images inside the body) are files too and are uploaded; use `is_inline` to tell them apart.
> * Attachments that are not files, such as an attached email, a calendar item or a link to a file in OneDrive or SharePoint, are not downloaded.
> * When a file cannot be downloaded or uploaded, the email is retried on the next runs. On regular runs the run ends as a partial success; on the first load and on a Full Sync the run keeps every file it could save and shows a warning (it is reported as failed when no file could be saved or when an email is given up after 5 runs).
>
> **Key fields:**
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `message_id` | String | Email the attachment belongs to (`Email.id`). |
> | `attachment_id` | String | Identifier of the attachment within the email. |
> | `last_modified_date_time` | DateTime | Last change of the email when the attachment was read (UTC). Used as the incremental replication key. |
> | `received_date_time` | DateTime | When the email was received (UTC). |
> | `attachment_name` | String | Original file name of the attachment in Outlook. |
> | `content_type` | String | MIME type of the attachment as reported by Outlook. |
> | `attachment_size` | Integer | Size of the attachment in Outlook, in bytes. |
> | `is_inline` | Boolean | Whether the attachment is inline (for example, an image shown in the body). |
> | `_nekt_file_name` | String | File name of the attachment. |
> | `_nekt_file_size` | Integer | Size of the uploaded file in bytes. |
> | `_nekt_mime_type` | String | MIME type of the uploaded file. |
> | `_nekt_file_id` | String | ID of the file created in the Nekt volume. |
> | `_nekt_uploaded_at` | DateTime | When the file was uploaded to Nekt. |

> [accordion] Mail Folder
>
> All mail folders of the mailbox, including subfolders and hidden folders, with their full path. The table is replaced on every run.
>
> **Key fields:**
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | String | Unique identifier of the folder. Emails reference it in `parent_folder_id`. |
> | `display_name` | String | Name of the folder as shown in Outlook. |
> | `folder_path` | String | Full path of the folder, for example `Inbox/Clients/ACME`. |
> | `well_known_name` | String | Outlook name of a default folder (`inbox`, `drafts`, `sentitems`, `deleteditems`, `junkemail`, `outbox`, `archive`); empty for your own folders. |
> | `parent_folder_id` | String | Parent folder (the top of the mailbox for top-level folders). |
> | `child_folder_count` | Integer | Number of immediate subfolders. |
> | `unread_item_count` | Integer | Number of unread items in the folder. |
> | `total_item_count` | Integer | Number of items in the folder. |
> | `is_hidden` | Boolean | Whether the folder is hidden in Outlook. |
> | `is_spam_or_trash` | Boolean | Whether the folder is Junk Email or Deleted Items, or a subfolder of one of them. |

# Data Model

```mermaid theme={null}
graph LR;
    Email("Email");
    EmailAttachments("Email Attachments");
    MailFolder("Mail Folder");
    Email -- "parent_folder_id = id" --> MailFolder;
    EmailAttachments -- "message_id = Email.id" --> Email;
```

# Use Cases for Data Analysis

**Emails per folder.** Join each email to the path of the folder that holds it.

> [accordion] Example SQL (Trino / AWS Athena)
>
> ```sql theme={null}
> SELECT
>   f.folder_path,
>   COUNT(*) AS emails,
>   SUM(CASE WHEN e.is_read THEN 0 ELSE 1 END) AS unread
> FROM nekt_raw.microsoft_outlook_email e
> JOIN nekt_raw.microsoft_outlook_mail_folder f
>   ON e.parent_folder_id = f.id
> GROUP BY f.folder_path
> ORDER BY emails DESC;
> ```

**Find the files of an email.** List the attachments saved to the volume for emails from a given sender.

> [accordion] Example SQL (Trino / AWS Athena)
>
> ```sql theme={null}
> SELECT
>   e.received_date_time,
>   e.subject,
>   a.attachment_name,
>   a._nekt_file_id
> FROM nekt_raw.microsoft_outlook_email e
> JOIN nekt_raw.microsoft_outlook_email_attachments a
>   ON a.message_id = e.id
> WHERE e.from_address = 'billing@example.com'
> ORDER BY e.received_date_time DESC;
> ```

> [!NOTE]
>
> Replace schema and table names (`nekt_raw`, `microsoft_outlook_email`, ...) with the layer and table names you configured for the source.

## Implementation Notes

### Extraction Behavior

* **Email** reads every folder in one ordered query by last change, page after page, up to the moment the run started. Changes made while the run is in progress are picked up by the next run.
* An email moved to another folder keeps its `id`, so its row is updated with the new `parent_folder_id`.
* Emails deleted permanently in Outlook are not removed from the table. With **Include SPAM and Trash** off, an email moved to Deleted Items keeps its last synced row.
* Microsoft limits how many requests a mailbox can receive. When it asks Nekt to slow down, the run waits as requested and continues, so large first syncs can take a while.

### Attachments

* Files are downloaded one at a time, up to Outlook's limit of 150 MB per file.
* Whenever an email changes (for example, it is read, flagged or moved to another folder), all its attachments are downloaded and uploaded again, replacing the files with the same names in the volume. Nothing is duplicated, but bulk actions such as "mark all as read" on a large folder make the next run longer. For large mailboxes, we recommend scheduling this source once a day.
* A Full Sync uploads every file again, under the same file names in the volume.
* If you turn on the attachments option for an existing source, run a Full Sync to also collect the attachments of emails synced before.

## Skills for agents

<Snippet file="agent-skills-intro.mdx" />

> [card] [Download Microsoft Outlook skills file](https://docs.nekt.com/sources/microsoft-outlook.md)
>
> Microsoft Outlook connector documentation as plain markdown, for use in AI agent contexts.


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