---
title: "Connect a Microsoft 365 mailbox"
description: "Connect a Microsoft 365 support mailbox with the Outpost Mail app, limited to that one mailbox, or by signing in as the mailbox."
url: "https://support.outpostplatform.com/service-desk/connect-microsoft-365/"
product: "depot"
type: "how-to"
status: "draft"
ai_summary: "Microsoft 365 app connection (recommended): an admin approves the Outpost Mail app, which has no mailbox access on its own, then runs a generated Exchange RBAC for Applications script granting read and send on one mailbox. It takes 30 minutes to 2 hours to apply, and the access check must pass first. Also sign in as the mailbox (can expire) and your own app."
availability:
  plans: ["enterprise", "msp"]
  permission: "mailbox:manage"
  preview: false
source: "https://gitlab.com/outpostplatform/docs/-/edit/main/src/content/docs/service-desk/connect-microsoft-365.md"
license: "CC BY 4.0"
---

# Connect a Microsoft 365 mailbox

Connect a Microsoft 365 mailbox, including a shared mailbox, so the mail sent
to it becomes tickets and your replies go out from it. When you finish,
Outpost can read and send from that one mailbox and no other. For how email
becomes tickets, see [Email to ticket](/service-desk/mailboxes/).

There are three ways to connect. Use the app connection unless you have a
reason not to.

| Method | What it needs | Trade-off |
| --- | --- | --- |
| **Microsoft 365 app connection** (recommended) | A Microsoft 365 admin to approve the app, and an Exchange admin to run a script | Nothing expires. Access is limited to one mailbox, and Outpost checks that it is. |
| **Sign in as the mailbox** | The mailbox's own sign-in | Quicker, but the sign-in can expire and has to be renewed. |
| **Your own Entra app registration** | An app registration you create and manage | You manage the secret and its expiry, and the access it grants. |

## Before you begin

- You need `mailbox:manage` in the console.
- For the app connection, you need a Microsoft 365 admin who can approve an
  app for the organization, and an Exchange admin who can run PowerShell
  against Exchange Online. They can be the same person.
- For the script, install the `ExchangeOnlineManagement` and
  `Microsoft.Graph` PowerShell modules on the computer you run it from.
- Remote Outpost cannot connect to Microsoft 365. Use
  [IMAP](/service-desk/connect-imap/) there.

## Connect with the app connection

The Outpost Mail app holds no mailbox permissions of its own. Approving it
only creates it in your organization. The script in step 6 gives it access to
this one mailbox through Exchange's role-based access control for
applications.

1. In the console, go to **Settings** > **Mailboxes** and select **Add
   mailbox**.
2. In **Support address**, enter the address, such as `support@contoso.com`.
   In **Name**, optionally enter how the mailbox is listed in Outpost. Select
   **Continue**.
3. The wizard shows **Looks like Microsoft 365**. Choose **Microsoft 365 app
   connection** and select **Continue**.
4. Select **Connect to Microsoft 365**. Sign in with a Microsoft 365 admin
   account and approve the Outpost Mail app.
5. Microsoft returns you to the wizard, which shows **The Outpost Mail app is
   approved. Now limit it to this mailbox.**
6. Under **Limit access to this mailbox**, select **Copy script**. Run it in
   PowerShell, and sign in as an Exchange admin when asked.

   The script has your address filled in. It looks like this:

   ```powershell
   # Gives Outpost Mail access to ONE mailbox: support@contoso.com
   Connect-ExchangeOnline
   Connect-MgGraph -Scopes "Application.Read.All"
   $AppId = "<outpost-mail-app-id>"
   $Sp = Get-MgServicePrincipal -Filter "appId eq '$AppId'"
   New-ServicePrincipal -AppId $AppId -ObjectId $Sp.Id -DisplayName "Outpost Mail"
   New-ManagementScope -Name "Outpost Mail - support" -RecipientRestrictionFilter "PrimarySmtpAddress -eq 'support@contoso.com'"
   New-ManagementRoleAssignment -App $AppId -Role "Application Mail.ReadWrite" -CustomResourceScope "Outpost Mail - support"
   New-ManagementRoleAssignment -App $AppId -Role "Application Mail.Send" -CustomResourceScope "Outpost Mail - support"
   ```

   It registers the Outpost Mail app with Exchange, creates a management
   scope that matches only this mailbox's address, and assigns the app the
   **Application Mail.ReadWrite** and **Application Mail.Send** roles within
   that scope. Use the script from the wizard rather than this example: it
   carries the real app ID.

7. Select **I ran the script, test it**. The wizard runs the test. See
   [Verify](#verify).
8. In the **Routing** step, choose where new tickets land, then select **Save
   mailbox**.

Microsoft takes 30 minutes to 2 hours to apply the script. Until it does, the
**Access limited to this mailbox** check fails with **Outpost Mail can still
reach other mailboxes in your organization.** That is expected. Close the
wizard, wait, and select **Test** on the mailbox's row later. The mailbox
stays off until the check passes, and turning it on before then is refused
with **Run the connection test first. Outpost needs to confirm it can reach
only this mailbox.**

### How the access check works

Outpost asks Microsoft 365 for a mailbox in your organization that does not
exist. When access is limited to your support mailbox, Microsoft refuses the
request, and the check passes. When Microsoft answers any other way, the app
can reach mailboxes it should not, and the check fails. Outpost never turns on
a mailbox that fails this check.

## Connect by signing in as the mailbox

Outpost signs in as the mailbox itself. The sign-in stops working if the
account's password changes, an admin revokes its sessions, or the token
expires. Outpost raises an alert 14 days before it expires so you can sign in
again, and it alerts at once if the sign-in stops working. For a shared
support mailbox, the app connection is the better choice.

1. In the wizard, choose **Sign in as the mailbox** and select **Continue**.
2. Select **Sign in to Microsoft 365** and sign in as the mailbox's account.
3. The wizard shows **Signed in as** and the account. Select **Test it**.
4. In the **Routing** step, select **Save mailbox**.

To renew the sign-in, select **Reconnect** on the mailbox's row and sign in
again. Outpost picks up where it stopped, and mail that arrived in the
meantime still becomes tickets.

## Connect with your own app registration

Use this when your organization manages its own Entra app registration.

1. In Microsoft Entra, create an app registration with a client secret. Grant
   it the Microsoft Graph application permissions **Mail.ReadWrite** and
   **Mail.Send**, and grant admin consent.
2. Limit the app to the support mailbox, as the script above does for the
   Outpost Mail app. Without that, the app can read every mailbox in your
   organization.
3. In the wizard, under **Advanced**, choose **Your own Entra app
   registration** and select **Continue**.
4. Enter the **Application (client) ID**, the **Directory (tenant) ID** from
   the app registration's **Overview** page, and the **Client secret**.
5. Select **Save and test**.

Outpost stores the secret encrypted and never shows it again. When the secret
expires in Entra, the mailbox shows **Reconnect needed**. Create a new secret,
select **Reconnect**, and enter it.

## Verify

The test runs these checks in order, and stops at the first that fails:

| Check | Passes when |
| --- | --- |
| **Connect** | Outpost reached Microsoft 365. |
| **Sign in** | Microsoft accepted the connection. |
| **Access limited to this mailbox** | The app can reach only this mailbox. Applies to the app connection only. |
| **Send a test message** | Outpost sent a message from the mailbox to itself. |
| **Receive the test message** | The message arrived and Outpost collected it. |

Each check shows **Passed**, **Warning**, **Failed**, **Waiting**, or
**Skipped**. The
receive check finishes once the mailbox is on and the message arrives. The
test message is never turned into a ticket.

In **Settings** > **Mailboxes**, the mailbox shows **Connected**. Send a
message to the support address from another account. A ticket appears in the
mailbox's queue, and the message is marked as read in the mailbox.

## If something goes wrong

| Message | Cause | Fix |
| --- | --- | --- |
| **Approving the Outpost Mail app needs a Microsoft 365 admin account.** | The account that signed in is not an admin. | Select **Connect to Microsoft 365** again and sign in as an admin. |
| **Microsoft has not finished applying the approval. Wait a minute, then connect again.** | The approval is still spreading through Microsoft 365. | Wait a minute and connect again. |
| **You signed in to a different Microsoft 365 organization than the one this address belongs to.** | The admin account belongs to another organization. | Sign in with an admin of the organization that hosts the address. |
| **Finish the sign-in in the same browser you started it in.** | The sign-in finished in another browser or profile. | Start again and finish in the same browser. |
| **Outpost Mail can still reach other mailboxes in your organization.** | The script has not run, or Microsoft has not applied it yet. | Run the script, wait up to 2 hours, then test again. |
| **The server refused SMTP sign-in.** | A Microsoft 365 mailbox was set up with IMAP and SMTP. | Connect it with the app connection instead. See [Connect a mailbox with IMAP](/service-desk/connect-imap/#microsoft-365-and-smtp-auth). |

For a mailbox that stops working later, see
[Troubleshoot a support mailbox](/service-desk/mailbox-health/).

## Next steps

- [Email threading](/service-desk/email-threading/)
- [Suspended mail](/service-desk/suspended-mail/)
- [Client email domains](/service-desk/mailboxes/#client-email-domains)