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

# Mailbox connections

> Connect IMAP or Microsoft 365 mailboxes to Ekso for email-based ticketing.

## Overview

A mailbox connection tells Ekso how to access an external email account. Once connected, you can set up [ticketing](/guide/concepts/ticketing) to turn inbound emails into work items, reply from within Ekso, and maintain threaded conversations.

You manage mailbox connections under **Settings > Mailbox**. Ekso supports two connection types: IMAP and Microsoft 365.

### IMAP

Connect to any IMAP-compatible mail server — Google Workspace, Fastmail, or any standard email provider.

| Property         | Description                                         | Default |
| ---------------- | --------------------------------------------------- | ------- |
| Name             | Display name for this mailbox connection            | —       |
| Connection type  | Select **Imap**                                     | —       |
| Server           | IMAP server address (e.g., `imap.gmail.com`)        | —       |
| Port             | IMAP port                                           | 993     |
| Username         | Mailbox account username                            | —       |
| Password         | Mailbox account password                            | —       |
| SMTP server      | Server for sending replies (e.g., `smtp.gmail.com`) | —       |
| SMTP server port | SMTP port                                           | 587     |
| Inbox folder     | Which folder to watch for new emails                | Inbox   |

IMAP connections track the last processed email by its UID (a unique message identifier assigned by the mail server). Each processing cycle queries for unseen messages or messages with a UID greater than the last processed one. This means IMAP picks up exactly where it left off, message by message.

### Microsoft 365

Connect to Microsoft 365 mailboxes using OAuth authentication through Microsoft Graph.

| Property                  | Description                                                         |
| ------------------------- | ------------------------------------------------------------------- |
| Name                      | Display name for this mailbox connection                            |
| Connection type           | Select **Microsoft**                                                |
| Email address             | Email address of the mailbox to be used                             |
| OAuth tenant ID           | Your Azure AD tenant ID (found in admin.microsoft.com)              |
| OAuth client ID           | The application client ID from your Azure app registration          |
| OAuth client secret value | The secret **value** (not the secret ID) from your app registration |
| Inbox folder              | Which folder to watch for new emails (default: Inbox)               |

#### Azure app registration

Before you can connect a Microsoft 365 mailbox, you need an app registration in Microsoft Entra with the correct Microsoft Graph permissions.

<Steps>
  <Step title="Open app registrations">
    Go to [entra.microsoft.com](https://entra.microsoft.com) → **App registrations** → select your app (or create a new one).
  </Step>

  <Step title="Add API permissions">
    Click **API permissions** → **+ Add a permission**.
  </Step>

  <Step title="Select Microsoft Graph">
    Select **Microsoft Graph** → **Application permissions**.
  </Step>

  <Step title="Add required permissions">
    Search for and add the following permissions:

    | Permission                    | Type        | Description                               | Admin consent |
    | ----------------------------- | ----------- | ----------------------------------------- | ------------- |
    | `Mail.Read`                   | Application | Read mail in all mailboxes                | Yes           |
    | `Mail.ReadBasic`              | Application | Read basic mail in all mailboxes          | Yes           |
    | `Mail.ReadBasic.All`          | Application | Read basic mail in all mailboxes          | Yes           |
    | `Mail.ReadWrite`              | Application | Read and write mail in all mailboxes      | Yes           |
    | `Mail.Send`                   | Application | Send mail as any user                     | Yes           |
    | `MailboxFolder.ReadWrite.All` | Application | Read and write all users' mailbox folders | Yes           |
  </Step>

  <Step title="Grant admin consent">
    Click **Grant admin consent for \[your organization]** and confirm. All six permissions require admin consent.
  </Step>
</Steps>

<Note>
  These are **Application** permissions, not Delegated. This means Ekso accesses the mailbox directly without a signed-in user — which is why admin consent is required for all six permissions. If you already have an app registration for [Entra SSO](/guide/concepts/authentication#setting-up-entra-id), you can add these permissions to the same registration.
</Note>

<Tip>
  When creating a client secret under **Certificates & secrets**, copy the secret **value** — not the secret ID. The value is only shown once at creation time. This is the value you enter in the **OAuth client secret value** field.
</Tip>

Microsoft connections track the last processed date rather than UIDs. Each processing cycle queries Microsoft Graph for messages received after the last processed timestamp. The **Start from** date in the [ticketing configuration](/guide/concepts/ticketing#ticketing-configuration) sets the initial boundary — Ekso only processes emails received on or after this date, so historical emails in the mailbox are not accidentally converted into tickets.

<Note>
  IMAP and Microsoft 365 use different tracking mechanisms. IMAP resumes by message UID (precise per-message tracking). Microsoft 365 resumes by received date (time-window based). Both approaches prevent duplicate processing, but the Microsoft approach means the **Start from** date on the [ticketing configuration](/guide/concepts/ticketing#ticketing-configuration) is especially important for controlling what gets processed on first activation.
</Note>

<Tip>
  Use Microsoft 365 if your organization is already on Microsoft 365. The OAuth approach avoids storing email passwords and supports modern authentication policies like conditional access.
</Tip>

## Credentials

All mailbox credentials are encrypted at rest before storage.

## Testing connections

Use the **connection test** to verify that Ekso can connect to the mail server with the provided credentials. Test before setting up [ticketing](/guide/concepts/ticketing) to catch configuration issues early.

For end-to-end ticketing pipeline testing, see [testing](/guide/concepts/ticketing#testing) in the ticketing guide.