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

# Connect Outlook

> Send and read emails from your Outlook or Microsoft 365 account

Connect an Outlook or Microsoft 365 mailbox so Hiveku can send, read, or manage email across your CRM workflows, sales agents, and automations.

<Info>
  Before you start: [Set up a Microsoft Azure OAuth app](/how-tos/microsoft-oauth-app). You only do this once — the same app powers every Outlook connection.
</Info>

## Pick Your Scope

Outlook supports several access levels via Microsoft Graph. Pick the smallest scope that does what you need:

| Scope               | Microsoft Graph permissions                                   | What it does                          |
| ------------------- | ------------------------------------------------------------- | ------------------------------------- |
| **Read-only**       | `offline_access Mail.Read`                                    | Read messages, folders                |
| **Send only**       | `offline_access Mail.Send`                                    | Send new emails; can't read inbox     |
| **Full access**     | `offline_access Mail.ReadWrite Mail.Send`                     | Read, send, move, flag                |
| **Full + Calendar** | `offline_access Mail.ReadWrite Mail.Send Calendars.ReadWrite` | Full mail + calendar event management |

<Info>
  `offline_access` is included in every option — without it, Microsoft won't issue a refresh token, and the connection would expire every hour. Hiveku adds it automatically.
</Info>

## Pick Your Tenant

Tenant controls which Microsoft accounts can authorize the connection. Set this when you registered the Azure app, but you can override per connection:

* **Common** — any Microsoft account (work, school, or personal) can authorize. Most flexible.
* **Specific tenant ID** — only users in that tenant can authorize. Use when you want to restrict access to a single organization.

<Warning>
  If your Azure app was registered as **single tenant**, the only accounts that can authorize are in that tenant. Using `common` in Hiveku won't override the Azure app's configuration — that's a Microsoft-side setting. See the [Microsoft OAuth App setup guide](/how-tos/microsoft-oauth-app) for details.
</Warning>

## Connect the Mailbox

<Steps>
  <Step title="Open the integration">
    Go to **CRM > Email Connections > Add Connection > Outlook**.
  </Step>

  <Step title="Select your Microsoft OAuth app">
    Pick the Microsoft app you registered under **Settings > OAuth Apps**. If you see no apps in the dropdown, create one first — see [Set up a Microsoft Azure OAuth app](/how-tos/microsoft-oauth-app).
  </Step>

  <Step title="Choose your scope">
    Pick one of:

    * **Read-only** — for reading inboxes
    * **Send only** — for outbound email
    * **Full access** — for general CRM use
    * **Full + Calendar** — for sales agents booking meetings
  </Step>

  <Step title="Choose your tenant">
    * **Common** for multi-tenant
    * **Specific tenant ID** to restrict to a single Microsoft 365 tenant
  </Step>

  <Step title="Authorize with Microsoft">
    Click **Authorize with Microsoft**. You're redirected to a Microsoft consent screen showing your app name and the scopes you're requesting. Sign in, review, and click **Accept**.
  </Step>

  <Step title="Confirm the connection">
    You return to Hiveku, where the Outlook connection shows:

    * Your email address
    * Active scopes
    * Status **Active**
  </Step>
</Steps>

## Admin Consent

Some Graph scopes (especially `Mail.ReadWrite` on some tenants) can be configured to require admin consent. If your users hit "admin consent required" during authorization, your Microsoft 365 admin should:

<Steps>
  <Step title="Open the Azure app">
    Go to [portal.azure.com](https://portal.azure.com) > **App registrations** > select the app.
  </Step>

  <Step title="Grant admin consent">
    Navigate to **API permissions** and click **Grant admin consent for \[tenant]**. This pre-consents the permissions for all users in the tenant so each user doesn't need to request admin approval individually.
  </Step>
</Steps>

## Connect Multiple Mailboxes

Repeat the flow for each Outlook or Microsoft 365 account — each becomes its own connection.

## Verify the Connection

* Connection status on the Email Connections page shows **Active**
* Send a test email from the CRM — it arrives from your Outlook address
* For read scopes, check a test message appears in the CRM's inbox view

## Changing the Scope Later

OAuth tokens are scope-locked. To change a connection from read-only to full, for example:

<Steps>
  <Step title="Disconnect the existing Outlook connection">
    Click the menu next to the connection and choose **Disconnect**.
  </Step>

  <Step title="Reconnect with the new scope">
    Run the flow again with the new scope selected.
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="AADSTS65001: consent required">
    Either the user hasn't consented yet, or admin consent is required and hasn't been granted. Retry the flow — the user sees a consent prompt. If consent is gated to admin-only, your Microsoft 365 admin must grant it in Azure Portal first.
  </Accordion>

  <Accordion title="'Admin consent required for this scope'">
    Some scopes (like `Mail.ReadWrite` in certain tenants) require admin pre-approval. Your Microsoft 365 admin should go to **Azure Portal > App registrations > \[your app] > API permissions > Grant admin consent for \[tenant]**.
  </Accordion>

  <Accordion title="User can't authorize — 'account not in this tenant'">
    Your Azure app is configured as single-tenant, so only users in that tenant can authorize. Either switch the app to multi-tenant in Azure (**Authentication > Supported account types**) and use `common` in Hiveku, or ensure the user is in the correct tenant.
  </Accordion>

  <Accordion title="Token refresh failing after a while">
    Usually means your Azure client secret expired. Create a new secret in **Azure Portal > App registrations > \[your app] > Certificates & secrets**, then update it in **Hiveku > Settings > OAuth Apps**. Existing connections may need to reconnect once.
  </Accordion>

  <Accordion title="Consent screen doesn't show all the scopes I expected">
    If `offline_access` isn't listed, the connection won't get a refresh token and will expire. Re-check your scope selection in Hiveku. If a mail or calendar scope is missing, confirm the permission is added in your Azure app under **API permissions**.
  </Accordion>
</AccordionGroup>

## What's Next?

<CardGroup cols={2}>
  <Card title="Microsoft OAuth App" icon="microsoft" href="/how-tos/microsoft-oauth-app">
    Review the Azure app setup
  </Card>

  <Card title="Run Sales Sequences" icon="list-ol" href="/how-tos/crm-sales-sequences">
    Personal OAuth cadences — sent from this Outlook mailbox
  </Card>

  <Card title="Work with the AI SDR" icon="robot" href="/how-tos/ai-sdr">
    The AI drafts and sends from your connected Outlook on approval
  </Card>

  <Card title="Send Emails" icon="paper-plane" href="/how-tos/send-emails">
    Use your Outlook connection in workflows
  </Card>
</CardGroup>