Connect Email (Microsoft 365)

This guide walks you through connecting a Microsoft 365 account to Pinchy so your agents can work with email — reading, searching, drafting, and sending messages.

The setup has two parts: registering an app in Azure (one-time), then connecting the account in Pinchy.

Note

One app, many mailboxes. You register the Azure app (Client ID, Secret, and optional Tenant ID) once, then connect as many Microsoft 365 mailboxes as you like through it. The app and the mailboxes have separate lifecycles — you manage the app in the Connected apps section, below the Integrations list where each mailbox appears. See Connect Email for the overview.

Prerequisites

• Pinchy is running with HTTPS enabled (see Lock Pinchy to a Domain)
• You're logged in as an admin in Pinchy
• Access to the Azure portal with permission to register app registrations in your tenant

Caution

Microsoft OAuth requires HTTPS. The Add Integration wizard shows a warning and blocks the Microsoft flow when Pinchy runs without HTTPS.

Part 1: Register an app in Azure

Microsoft requires you to register your Pinchy instance as an OAuth application in Azure before users can sign in. This is a one-time step per Pinchy installation.

1.1 Create the app registration

1. Sign in to portal.azure.com

2. Navigate to Microsoft Entra ID → App registrations → New registration

3. Fill in the form:

   • Name — enter Pinchy (this name appears on the Microsoft consent screen)

   • Supported account types — choose based on your situation:

     • Accounts in this organizational directory only — all users are in one Microsoft 365 tenant (recommended for most companies)
     • Accounts in any organizational directory — users are spread across multiple tenants
     • Accounts in any organizational directory and personal Microsoft accounts — also support Outlook.com personal accounts

   • Redirect URI — select Web platform and paste the redirect URI shown in the Pinchy wizard (Settings → Integrations → Add Integration → Microsoft, step 1)

4. Click Register

Tip

Create a dedicated app registration for Pinchy rather than reusing an existing one — it keeps credentials organized and makes it easy to revoke access later.

1.2 Add API permissions

Permissions (scopes) define what data your app can access.

1. In the left sidebar, click API permissions → Add a permission → Microsoft Graph → Delegated permissions

2. Search for and add these permissions:

   • Mail.ReadWrite — read and search emails, create drafts
   • Mail.Send — send emails
   • offline_access — receive refresh tokens so Pinchy stays connected without repeated sign-ins
   • User.Read — identify the connected account

3. Click Add permissions

4. Click Grant admin consent for [your tenant] and confirm

Note

Admin consent is required for offline_access to return refresh tokens in most tenant configurations. Without it, users may be prompted to sign in repeatedly.

1.3 Create a client secret

1. In the left sidebar, click Certificates & secrets → New client secret
2. Give it a description (e.g. "Pinchy") and choose an expiry
3. Click Add
4. Copy the Value immediately — Azure may not show it again later. Missed it? Just create a new client secret (adding one doesn't invalidate the app or any connected mailbox) and paste it into Pinchy under Connected apps → Edit.

Caution

Copy the Value column, not the Secret ID. The Value is what Pinchy needs. The Secret ID is an internal Azure identifier and won't work as a client secret.

1.4 Copy your app identifiers

From the app registration Overview page, copy:

• Application (client) ID — identifies your app
• Directory (tenant) ID — identifies your Microsoft 365 tenant

You'll need both in the next part.

---

Part 2: Connect the account in Pinchy

1. Open the Add Integration wizard

   In Pinchy, go to Settings → Integrations and click Add Integration, then select Microsoft.

2. Enter your app credentials

   Paste the Client ID and Client Secret from Part 1.

   Optionally paste the Tenant ID. Leave it blank to allow any work or school account — Pinchy uses Microsoft's organizations endpoint by default, which does not accept personal Microsoft accounts. Enter your tenant ID to restrict access to your organization only, or enter common to also allow personal Outlook.com accounts to connect (only relevant if your app registration's Supported account types includes personal Microsoft accounts — see 1.1).

   Click Save & Continue.

   Pinchy encrypts these credentials and stores them on your server — they never leave your infrastructure.

3. Connect a Microsoft account

   Click Connect Microsoft Account. Microsoft's consent screen opens — sign in with the account whose email the agent should access and grant the requested permissions.

4. Verify the connection

   You're redirected back to Pinchy. The integration list now shows the connected email address with a green "Connected" status.

For subsequent Microsoft connections (a second mailbox), the credentials step is skipped — you go straight to "Connect Microsoft Account". The app you registered in Part 1 is reused for every Microsoft 365 mailbox on this Pinchy instance.

---

Managing the app later

The Azure app you registered in Part 1 lives in the Connected apps section of Settings → Integrations, below the list of connected mailboxes. You can update or reset it at any time — the app and the connected mailboxes are managed separately.

Note

Earlier versions of Pinchy had no way to change the Microsoft app details after you first entered them. That's no longer the case — Edit and Reset in the Connected apps section let you update or clear the credentials whenever you need to.

Edit the app credentials

Click Edit on the Microsoft row to update the Client ID, Client Secret, or Tenant ID. The Client ID and Tenant ID stay pre-filled and you can change either on its own. The Client Secret is never displayed — leave it blank to keep the stored secret, or paste a new one to rotate it. Changes apply to every Microsoft 365 mailbox connected through this app.

Rotate the client secret before it expires

The Azure portal caps client secrets at 24 months — you can't create a longer-lived one there. When a secret expires, Pinchy can no longer refresh tokens and every mailbox stops working. Plan the rotation ahead of the expiry date:

1. In Azure, create a new client secret under Certificates & secrets (see Part 1, step 1.3).
2. In Pinchy, click Edit on the Microsoft row and paste the new secret's Value.

Rotating only the client secret keeps every mailbox connected: the existing refresh tokens stay valid, so agents keep working without interruption.

Changing the Client ID points Pinchy at a different app registration. The old refresh tokens no longer apply, so every mailbox must be reconnected afterward.

Reset the app

Click Reset on the Microsoft row to clear the stored credentials entirely. This is the deliberate way to remove an app — it stays configured until you reset it, even after you've removed its last mailbox.

Caution

Resetting the app disconnects every Microsoft 365 mailbox connected through it. The confirmation dialog tells you exactly how many mailboxes will be affected before you commit. Each one must be reconnected afterward. This can't be undone.

---

Part 3: Grant agent email permissions

A connection alone doesn't give any agent access. You must explicitly grant permissions per agent.

Note

Only shared agents have a Permissions tab. Personal agents can't be granted integration access — email permissions are a shared-agent feature.

1. Open the agent you want to connect to email

2. Click the gear icon to open Agent Settings

3. Select the Permissions tab

4. In the Email section, select the connected account and check the operations this agent may perform:

   • Read messages — list, read, and search emails
   • Create drafts — create draft emails (saved but not sent)
   • Send messages — send emails immediately (cannot be undone)

5. Click Save & Restart and confirm. Permission changes restart the agent runtime, so active chats are briefly disconnected.

Caution

Send messages is a powerful permission. The agent can send email from the connected account without human review. Consider using Create drafts instead — a human reviews and sends drafts manually.

---

Test it

Open the agent's chat and try a few queries:

• "Show me my latest unread emails"
• "Search for emails from finance@example.com about invoices"
• "Draft a reply to the last email saying we'll process it today"
• "How many unread emails do I have?"

---

Available tools

When email permissions are granted, the agent gets access to these tools:

| Tool | Permission required | Description | | ---------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | email_list | Read | List emails from a folder (INBOX, SENT, DRAFTS, TRASH, SPAM; defaults to INBOX). Supports filtering by read status. | | email_read | Read | Read the full content of a specific email by ID. Lists any attachments with their IDs. | | email_get_attachment | Read | Download an email attachment into the agent's workspace. | | email_search | Read | Search emails using structured fields: from, to, subject, text, unread, sinceDays, folder, limit (e.g. { from: "user@example.com", subject: "invoice", sinceDays: 7 }). text is a free-text match across sender, subject, and body — use it to find a phrase mentioned in the message content, like an invoice number. | | email_draft | Draft | Create a draft email. Can also create reply drafts with replyTo. | | email_send | Send | Send an email immediately. Can also send replies with replyTo. |

Note

Combining text with unread or sinceDays is best-effort on Microsoft 365: Graph can't run full-text search and structural filters together, so Pinchy fetches the free-text matches first and then filters that page for unread/date client-side, rather than sorting the whole mailbox by date the way a plain unread/sinceDays search does.

Note

Microsoft Graph's direct-send endpoint doesn't return a message ID — only reply sends do. When email_send sends a brand-new message (no replyTo), the agent confirms the send succeeded but can't quote an ID for it. This is expected Graph API behavior, not an error.

---

Token refresh

Microsoft access tokens expire after about one hour. Pinchy automatically refreshes expired tokens using the stored refresh token — no action required.

Microsoft rotates refresh tokens on every use. Pinchy handles this automatically. If you see repeated sign-in prompts, verify that your app registration has offline_access granted and that admin consent was given.

If a refresh fails permanently — the account revoked access, or the client secret expired — the mailbox's card in Settings → Integrations switches to a red "Authentication failed" state. Open the mailbox's … menu, click Reconnect, then Reconnect via Microsoft in the dialog to restart the Microsoft sign-in flow. The mailbox keeps its existing agent permissions.

If the failure was caused by an expired client secret, rotating the secret in the Connected apps section (see Rotate the client secret before it expires) is enough for agents to resume on their next call — you don't need to reconnect every mailbox. A mailbox that already flipped to "Authentication failed", however, keeps showing that red badge until you clear it explicitly: click Test Connection (or Reconnect) on that mailbox's … menu.

---

Troubleshooting

AADSTS65001: The user or administrator has not consented to use the application

Grant admin consent in Azure → API permissions → Grant admin consent for [your tenant].

AADSTS50011: The redirect URI in the request did not match

The redirect URI in Azure must exactly match the one shown in Pinchy — including the https:// scheme and any trailing path. Check for extra spaces or a missing slash.

AADSTS700016: Application not found

The Client ID is incorrect or belongs to a different tenant. Double-check that you copied the Application (client) ID from the correct app registration.

Tenant ID not found

Pasting the wrong value into the Tenant ID field — for example the Application (client) ID instead of the Directory (tenant) ID — used to only surface as AADSTS90002 on Microsoft's own error page, with no way back to Pinchy. Pinchy now checks the Tenant ID when you click Save & Continue and shows the error inline on the settings form instead, so you can fix it on the spot without ever leaving Pinchy. Double-check that you copied the Directory (tenant) ID from the app registration's Overview page (see 1.4).

Client secret expired

Azure client secrets have a finite lifetime (24 months maximum). When a secret expires, Pinchy can no longer refresh tokens. Create a new client secret in Azure, then click Edit on the Microsoft row in the Connected apps section to paste the new Value. Because you're only rotating the secret, connected mailboxes stay attached and agents resume working on their next call — you don't need to reconnect them. See Rotate the client secret before it expires.

If a mailbox already flipped to the red "Authentication failed" badge before you rotated the secret, that badge doesn't clear on its own — click Test Connection (or Reconnect) on that mailbox's … menu to clear it once the new secret is in place.

"You didn't authorize the connection"

You clicked Cancel or Decline on Microsoft's consent screen instead of approving the requested permissions. Nothing changed on Pinchy's side — start the connection again from Connected apps and approve the requested scopes this time.

"Sign-in worked, but Pinchy couldn't finish connecting"

The consent step succeeded, but Pinchy couldn't exchange the authorization code for a token — almost always a stale or incorrect Client Secret. Double-check the Client Secret under Connected apps (see Edit the app credentials), then try connecting again.

Microsoft OAuth settings missing

If an admin resets or deletes the Microsoft OAuth app in Connected apps while mailboxes are still connected through it, agents fail with Microsoft OAuth settings missing — reconnect the mailbox or restore the OAuth app the next time their access token needs to refresh, and the mailbox flips to the red "Authentication failed" state. Recover by re-entering the app credentials in Connected apps (restoring the same Client ID/Secret re-enables existing refresh tokens) or by reconnecting the affected mailbox.

---

What's next

• Integrations — how connections and permissions work
• Agent Permissions — the full allow-list model