> For the complete documentation index, see [llms.txt](https://developer.ultimo.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.ultimo.net/connectors/exchange-online/email-import.md).

# Email import

The Microsoft Graph REST API can be used to access a user’s **mailbox in the cloud** on Exchange Online as part of Office 365.

**Applicable Ultimo version**: Rolling Release (Azure cloud)

### Implementation steps <a href="#implementation-steps" id="implementation-steps"></a>

To use OAuth to access a user’s mailbox using the Microsoft Graph API the Ultimo application must be registered with Microsoft Entra ID.

#### 1. Register Ultimo application with Microsoft Entra ID <a href="#id-1.-register-application-with-azure-active-directory" id="id-1.-register-application-with-azure-active-directory"></a>

1. Go to the [Azure portal](https://portal.azure.com/) and sign in. This account must be in the same directory as the account that will be used to access Exchange.
2. Select **Microsoft Entra ID** and then select **Manage** > **App Registrations** in the left side menu.
3. Click on **New Registration** and use the following values:
   1. Enter a **Name** for the application
   2. For **Supported account types** choose **Accounts in this organizational directory only**
   3. For **Redirect URI** choose **Web** and enter `https://{customer}.ultimo.net/OAuth2Callback` where `{customer}` should be replaced with the actual customer environment
4. Click **Register**. Then copy the value of the **Application (client) ID** and the **Directory (tenant) ID** and save it. This will be needed later.
5. Select **Certificates & secrets** in the left side menu and click **New client secret**. Enter a description and click **Add**.
6. Copy the **Value** of the added client secret and save it.

#### 2. Grant permissions <a href="#id-1.-register-application-with-azure-active-directory" id="id-1.-register-application-with-azure-active-directory"></a>

Two types of permissions can be used:&#x20;

* Application permissions
* Delegated permission

**Application permissions**

Note: the steps below will grant Ultimo access to all mailboxes in your organisation. To limit this, create an [application access policy](https://learn.microsoft.com/en-us/graph/auth-limit-mailbox-access).

1. Go to API permissions
2. Choose Microsoft Graph, select Application permissions and then add the following permissions: Mail.ReadWrite

**Delegated permissions**

When using delegated permissions, the signed-in user must have access to mailboxes that are used for email import.

1. Go to API permissions&#x20;
2. Choose Microsoft Graph, select Delegated permissions and then add the following permissions: Mail.ReadWrite

#### 3. Create credential in Ultimo <a href="#id-2.-create-credential-in-ultimo" id="id-2.-create-credential-in-ultimo"></a>

The application that was registered in the previous steps can be used to create a credential in Ultimo.

1. Go to the UCTool and select **Credentials** under **Authorisation**.
2. Click on the plus icon to create a new credential and use the following values:
   1. Enter an **Id** and **Description** for the credential
   2. When using application permissions, choose **Client credentials** as Grant type&#x20;

      When using delegated permissions, choose **Authorization code** as Grant type
   3. When using delegated permissions, for **Authorization URL** enter `https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize?prompt=select_account` where `{tenant-id}` should be replaced with the **Directory (tenant) ID** that was copied in the previous steps
   4. For **Access token URL** enter `https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token` where `{tenant-id}` should be replaced with the **Directory (tenant) ID** that was copied in the previous steps
   5. For **Client Id** enter the value of the **Application (client) ID** that was copied in the previous steps&#x20;
   6. For **Client secret** enter the value of the added client secret that was copied in the previous steps&#x20;
   7. When using application permissions, enter `https://graph.microsoft.com/.default` as **Scope**

      When using delegated permissions, enter `Mail.ReadWrite offline_access` as **Scope**
3. Click on the save icon.
4. Click on the key icon in the toolbar to get an access token.
5. You will be redirected to the Microsoft login screen. Sign in with the account that will be used to access the mailbox(es).
6. You will be redirected back to Ultimo.

The credential with the access token can now be used to authenticate with the Microsoft Graph API to access a mailbox. Apply the credential on the Email server accounts that have been set up in Ultimo.

#### &#x20;<a href="#id-2.-create-credential-in-ultimo" id="id-2.-create-credential-in-ultimo"></a>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.ultimo.net/connectors/exchange-online/email-import.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.