Microsoft 365 / Outlook Integration

Connect your Microsoft 365 or Outlook email account to Workestra to send emails, sync your inbox, and keep all your communications organized in one place.

Overview

The Microsoft 365 integration uses OAuth 2.0 with PKCE for secure authentication and the Microsoft Graph API for email operations. This ensures enterprise-grade security while providing seamless email functionality across all Workestra modules.

Key Features

---

Connecting Your Account

Step 1: Navigate to Integrations

1. Click Settings in the left sidebar
2. Select Integrations from the menu
3. Click on Outlook from the available integrations

Step 2: Initiate Connection

1. In the connection modal, review the permissions that will be requested
2. Click Connect Microsoft 365
3. You'll be redirected to Microsoft's sign-in page

Step 3: Microsoft Sign-In

1. Enter your Microsoft 365 email address
2. Complete your organization's authentication (password, MFA, etc.)
3. Review the permissions requested by Workestra

Step 4: Grant Permissions

Workestra requests the following Microsoft Graph permissions:

Step 5: Complete Connection

1. Click Accept to grant permissions
2. You'll be redirected back to Workestra
3. A "How much mail should we sync?" modal appears

Step 6: Pick a history range

Workestra asks how far back to pull your mailbox:

You can keep working while the sync runs. A progress card appears on the connection showing how many messages have been pulled, an ETA, and Pause / Resume / Cancel buttons. New mail arriving during the sync is picked up automatically — you don't have to wait for the historical backfill to finish before receiving new email.

---

Using Connected Email

Sending Emails

Once connected, you can send emails from various places in Workestra:

1. CRM Contact/Deal Pages � Click the email icon on any contact or deal
2. Inbox � Use the compose button in your Inbox
3. Support Tickets � Reply to tickets via email
4. Recruiting � Send candidate outreach emails

Selecting Your "From" Address

When composing an email:

1. Click the From dropdown
2. Select your connected Outlook account
3. The email will be sent using your Outlook address
4. Replies will appear in both Outlook and Workestra

Email Sync Behavior

---

Where your mail appears

Connected mail surfaces in several places in Workestra — all kept in sync.

Sidebar → Inbox

The single destination for email and activity notifications. Click Compose in the header to send a new message from any connected mailbox. Use the filter chips (All / Unread / Emails / Mentions / Assigned / per-module) to narrow the feed, and the per-account dropdown (shown when the Email chip is active) to focus on one mailbox at a time. Click any notification to open its detail panel.

CRM contact and deal pages

Each contact and deal page has an Email panel in the right rail that lists every thread tied to the counterparty. Mail is matched by:

1. An explicit link (set automatically by our trigger when a message's sender or recipient matches a contact's email address).
2. Fallback address match — even if auto-link didn't fire, mail with from_address or to_addresses matching the contact's email shows up.

Click Compose on the panel to reply in-context; the message is pre-linked to the contact and deal.

Support ticket pages

Same pattern — the ticket detail page surfaces every email thread associated with the customer contact or matching the customer's email address.

Recruiting candidate pages

Candidates have a dedicated Email tab alongside Overview, Resume, Evaluation, Interview, Timeline, and References. Threads with the candidate's email address are auto-linked; replies from the candidate appear here as soon as they sync.

---

Enterprise Features

Azure AD Single Sign-On (SSO)

If your organization uses Azure AD:

1. Click Sign in with Microsoft on the login page
2. Your organization's SSO flow handles authentication
3. No separate Workestra password needed

Admin Consent (Organization-wide)

For organizations requiring admin approval:

1. Your IT admin navigates to the admin consent URL
2. Grants permissions for the entire organization
3. Individual users can then connect without per-user consent

Contact your IT administrator if you see an error saying "admin consent required."

Multi-Factor Authentication (MFA)

Microsoft 365 MFA is fully supported:

• Authenticator apps
• SMS codes
• Hardware security keys
• Conditional Access policies

---

Managing Your Connection

Go to Settings > Integrations > Outlook to see every Outlook mailbox you've connected, its health, and the actions available on each.

Connection Health

Each connection shows a colored dot and status badge:

Manual Sync (Sync Now)

Every mailbox has a Sync now button next to it. Use it when:

• You just sent an email from Outlook on your phone and want it to appear in Workestra immediately.
• A mailbox is Stale and you don't want to wait for the next scheduled sync.
• You've just connected a mailbox and want to pull more history than the initial sync fetched.

The button runs a delta sync against Microsoft Graph (pulling only messages that changed since the last sync), renews the webhook subscription if it was expiring, and updates the status in place. You'll see a toast with the number of new emails pulled, or the specific error if it fails.

How Sync Actually Works

There are three layers, each a fallback for the one above:

1. Webhook notifications (near real-time). When you connect, Workestra registers a Microsoft Graph subscription against your inbox. New or updated messages trigger a push notification within seconds, and Workestra syncs just the changed messages.
2. Daily scheduled sync (fallback). Every 24 hours a background job walks every active mailbox and runs a delta sync. This covers any webhook events that got dropped (network hiccups, expired subscriptions, Microsoft side outages). It also renews Graph subscriptions that are within 24 hours of their 3-day expiry, so webhooks never go dark.
3. Manual Sync Now button (on demand). Described above — immediate, user-triggered.

Reconnecting

If your connection shows an Error badge (most commonly "token expired"):

1. Go to Settings > Integrations > Outlook
2. Click the trash icon on the failing connection to remove it
3. Click Connect again and complete the Microsoft sign-in flow

Disconnecting

To remove the connection:

1. Go to Settings > Integrations > Outlook
2. Click the trash icon next to the mailbox
3. Confirm

What happens when you disconnect:

• The webhook subscription is deleted from Microsoft Graph
• No new emails will sync
• Previously synced emails remain visible in Workestra
• Sent emails stay in your Outlook Sent folder
• Any shared mailboxes you added through this connection are disconnected at the same time (because they delegate their permission from it — see Shared mailboxes below)

---

Multiple Outlook accounts

You can connect more than one Microsoft 365 account — for example, your personal account and your work account — and send from either when composing email.

Adding a second account

1. Go to Settings > Integrations > Outlook
2. Click Add another account next to the existing connection
3. Microsoft will show you an account picker — pick the second account (or sign in with a different one)
4. Approve the permissions

Both accounts appear as separate rows in your Outlook settings, each with its own health and Sync now button.

Choosing which account sends

When composing email from any CRM contact, deal, ticket, or candidate, the From selector lists every connected mailbox. Your last choice is remembered per workspace.

---

Shared mailboxes

A shared mailbox is a Microsoft 365 mailbox that doesn't have a password of its own — it's accessed via delegated permissions from real users. Common examples: support@acme.com, sales@acme.com, careers@acme.com. Workestra can read and send from any shared mailbox you have access to, without you ever leaving the app.

Quick version:

1. Ask your Exchange admin to grant you Full Access on the shared mailbox (Exchange Admin Center → the shared mailbox → Mailbox delegation → Full Access).
2. In Workestra, go to Settings > Integrations > Outlook.
3. Click Add shared mailbox.
4. Type the shared mailbox address (e.g. support@acme.com) and click Add mailbox. Workestra will verify that Exchange has actually granted you access before creating the connection.
5. The shared mailbox appears in the list with a Shared badge, syncs on its own schedule, and is available in the From selector when composing email.

You never OAuth a shared mailbox directly — it uses the token from one of your personal Outlook connections as the delegate. If you disconnect that personal connection, any shared mailboxes delegating from it are disconnected too.

---

Troubleshooting

"Connection Failed" Error

Possible causes and solutions:

"Token Expired" Error

1. Click Reconnect on the Connected Accounts page
2. Sign in again with Microsoft
3. The connection will be restored

Emails Not Syncing

Check in order:

1. Open Settings > Integrations > Outlook and look at the connection's health badge.
   • Error → the message under the address tells you exactly what went wrong (expired token, Microsoft API error, etc.). Fix the specific issue (usually: reconnect).
   • Stale → click Sync now. This pulls any missed messages and renews the webhook subscription. If Sync now also fails, the toast will tell you why.
   • Never synced → the initial sync is still running. Wait a minute, or click Sync now to force it.
   • Healthy → sync is working; the missing messages may simply not have arrived yet. Check your Outlook directly first.
2. If you just sent a message from Outlook and want it in Workestra immediately, click Sync now — the push notification can take up to a few minutes, but manual sync is immediate.
3. If your inbox is very large (> 10,000 emails), the initial sync pulls a few hundred per cycle. Trigger Sync now a few times, or wait for the daily cron.

"Permission Denied" Error

If you previously denied permissions:

1. Disconnect the account in Workestra
2. Go to Microsoft Account Permissions
3. Remove Workestra from the list
4. Reconnect in Workestra and accept all permissions

---

Security & Privacy

How Your Data Is Protected

Data We Access

We can access:

• Email metadata (subject, sender, recipients, date)
• Email body content (text and HTML)
• Attachment metadata (name, size, type)
• Read/unread status
• Folder labels

We cannot access:

• Your Microsoft password
• Other users' mailboxes
• Files in OneDrive
• Teams messages
• Calendar events (unless explicitly enabled)

Data Retention

• Active connections: Email data is retained while connected
• Disconnected accounts: Previously synced emails are retained
• Deleted accounts: All email data is purged within 30 days

---

Frequently Asked Questions

Q: Can I connect multiple Microsoft 365 accounts? A: Yes. Click Add another account on the Outlook integration page. Microsoft will show an account picker so you can pick a different identity. Each account gets its own row, its own sync schedule, and its own health badge.

Q: Can I connect a shared mailbox like support@acme.com? A: Yes — see Shared Mailboxes. You don't OAuth the shared mailbox itself; instead you connect your own account and then add the shared mailbox via the Add shared mailbox button. Your Exchange admin must have granted you Full Access first.

Q: Does this work with Outlook.com (personal) accounts? A: Yes, both Microsoft 365 business accounts and Outlook.com personal accounts are supported for personal mailbox connections. Shared mailboxes are a Microsoft 365 business feature only.

Q: Will syncing delete emails from my Outlook? A: No. Workestra reads mail and tracks read/unread and label changes. It never deletes messages from your Outlook account.

Q: Can I use this with Exchange on-premises? A: No, this integration requires Microsoft 365 cloud or Outlook.com. On-premises Exchange is not supported.

Q: Why do I need to reconnect occasionally? A: Microsoft refresh tokens are valid for up to 90 days of inactivity. Regular use keeps them refreshed silently. If you go a long time without using Workestra — or if Microsoft invalidates the token for security reasons (password change, admin policy update) — you'll see an Error badge on the connection and just need to reconnect.

Q: Is my data shared with Microsoft? A: Microsoft provides the email service, so they have access to your email data as per their privacy policy. Workestra does not share your data with additional third parties.

Q: Do I need to reconnect my existing accounts to use shared mailboxes? A: Only if you connected before shared-mailbox support was added. The connection health page shows the Add shared mailbox button as disabled with a tooltip telling you to reconnect — do that and the new permissions will be on your token going forward.

---

Next Steps

• Historical backfill — Pick a range and pull your existing mail into Workestra
• Inbox — Unified destination for email + notifications (the new Compose button + per-account filter live there)
• Email in your modules — How mail surfaces on CRM, Support, and Recruiting pages
• Shared Mailboxes — Full setup guide for support@, sales@, etc.
• Sending Emails — Learn advanced email composition features
• Email Signatures — Set up professional signatures