Shared Mailboxes

A shared mailbox is a Microsoft 365 mailbox that doesn't have a password of its own. Several people in the organisation are granted Full Access and Send As permissions in Exchange, and they access it through their own credentials. Common examples:

• support@acme.com
• sales@acme.com
• careers@acme.com
• billing@acme.com

Workestra lets your team read, reply, and send from these mailboxes without ever opening Outlook — everything shows up in the same CRM / Support / Recruiting workflow as personal mail.

---

How it works under the hood

You don't sign in to a shared mailbox — it has no password. Instead:

1. You connect your own Microsoft 365 account to Workestra (normal OAuth flow).
2. Microsoft issues your account a token that includes the Mail.Read.Shared, Mail.ReadWrite.Shared, and Mail.Send.Shared scopes.
3. Exchange checks, on every request, whether your account has delegated access to the shared mailbox.
4. Workestra uses your token to call the shared mailbox's Microsoft Graph endpoint (/users/support@acme.com/messages instead of /me/messages).

This means:

• No second sign-in required when you add a shared mailbox — your personal Outlook token already carries the permission.
• Exchange admin permissions are the real gate. If Exchange hasn't granted your account access to the mailbox, Workestra can't see it either, and the Add shared mailbox form will show a clear 403 error.
• Disconnecting your personal Outlook account also disconnects the shared mailboxes you added through it — they lose the token that was delegating the permission.

---

Prerequisites

1. Your Exchange admin grants you Full Access

This is a Microsoft 365 administrative step — Workestra cannot do it for you.

1. Open the Exchange Admin Center
2. Navigate to Recipients → Mailboxes
3. Find the shared mailbox (e.g. support@acme.com) and click it
4. Open the Delegation tab (some tenants call this "Mailbox delegation")
5. Under Read and manage (Full Access), click Edit and add the user accounts that need access
6. Under Send as, click Edit and add the same users if they also need to send from that address
7. Save

Permission changes can take up to 60 minutes to propagate across Microsoft 365. If the Workestra flow fails with a 403 immediately after the admin grants access, wait a few minutes and try again.

2. Your personal Outlook connection includes the shared-mailbox scopes

If you connected your Outlook account to Workestra after shared-mailbox support was added, you already have the right scopes — nothing to do.

If you connected before that, the Add shared mailbox button will be disabled with a tooltip telling you to reconnect. To upgrade:

1. Go to Settings → Integrations → Outlook
2. Click the trash icon to disconnect your existing connection
3. Click Connect again and re-approve the permission list (the new list includes Mail.Read.Shared, Mail.ReadWrite.Shared, Mail.Send.Shared)
4. The Add shared mailbox button is now enabled

Your email history is not lost during this step — disconnecting only removes the OAuth token, not the synced messages already stored in Workestra.

---

Adding a shared mailbox

Once the prerequisites are in place:

1. Go to Settings → Integrations → Outlook
2. Click Add shared mailbox
3. Enter the full email address (UPN) of the shared mailbox, e.g. support@acme.com
4. Click Add mailbox

Workestra will:

• Call Microsoft Graph with your token against the shared mailbox's inbox as a probe — if access is denied, you see an immediate, specific error (see Troubleshooting below)
• Create a new connection row tagged with a Shared badge
• Register a real-time webhook subscription for the shared mailbox
• Trigger an initial sync

You'll see the mailbox appear in the list within seconds, with a Never synced → Healthy transition as the first sync completes.

---

Using a shared mailbox

Reading mail

Incoming mail to the shared mailbox flows into your Workestra Inbox and is visible alongside your personal mail. Each email is tagged with the mailbox it came to, so you can filter to only the shared mailbox if you want (e.g. "only show me support@").

Replying and sending as

When composing an email in any CRM contact, Support ticket, Recruiting candidate, or the Inbox itself, the From dropdown lists every connected mailbox including your shared mailboxes. Pick the shared address and the email goes out with that address as the visible sender.

Team visibility

Multiple users in the same workspace can add the same shared mailbox independently. Each user's connection is its own OAuth token, but the underlying mailbox is the same — so an email answered by Alice shows up as read for Bob the next time his sync runs. This matches Outlook's own behaviour.

---

Health and sync

Shared mailboxes appear as separate rows in the Outlook integration page with the same health badges as personal mailboxes:

Each shared mailbox has its own Sync now button, its own webhook subscription, and its own sync cursor. They do not share sync state with the personal mailbox that delegates their token.

---

Disconnecting a shared mailbox

To remove just the shared mailbox (keeping your personal Outlook connection intact):

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

What happens:

• The Graph webhook subscription for that shared mailbox is deleted.
• No new emails from that mailbox will sync.
• Previously synced messages from the shared mailbox remain visible in Workestra.
• Your personal Outlook connection is untouched.
• Exchange permissions are not changed — only your Exchange admin can revoke Full Access from the mailbox.

To disconnect all mailboxes at once, disconnect the personal Outlook connection — the shared rows that delegated from it will be removed automatically (cascade delete on the parent connection).

---

Troubleshooting

"Microsoft rejected access to this mailbox" (HTTP 403)

Your admin hasn't granted you Full Access, or the permission hasn't propagated yet.

• Confirm with your admin that your account is listed under Mailbox delegation → Full Access for the shared mailbox in Exchange Admin Center.
• If the admin just added you, wait up to 60 minutes for the change to propagate.
• If you're certain you have access but still see this error, test outside Workestra: open Outlook on the web, click your avatar → Open another mailbox, type the shared UPN, and confirm you can see the inbox. If Outlook can't open it either, the permission isn't actually in place.

"Microsoft 365 could not find a mailbox at …" (HTTP 404)

The email address you entered doesn't exist in your Microsoft 365 tenant. Double-check the spelling. Use the exact UPN (User Principal Name) from Exchange — which is usually, but not always, the primary SMTP address.

"This Outlook connection was authorised before shared-mailbox access was available"

Your existing OAuth token doesn't carry the .Shared scopes. See Prerequisites → Step 2 for the reconnect flow.

The shared mailbox is connected but nothing syncs

Check the badge:

• Never synced (blue) — wait a minute, or click Sync now.
• Stale (amber) — click Sync now. If it fails, the toast will show the reason.
• Error (red) — read the message under the mailbox address. The most common cause is that your parent personal connection's token expired; reconnect that one and the shared mailbox will recover automatically.

I can read incoming mail but can't send from the shared address

You have Full Access but not Send as in Exchange. They are separate permissions. Ask your admin to add you to the Send as (or Send on behalf of) list for the shared mailbox. No Workestra-side change is needed — the next send attempt will work once Exchange propagates the change.

Two users added the same shared mailbox — is that a problem?

No. Each user's connection is an independent OAuth delegation. They don't interfere. If one user disconnects the mailbox, the other's connection keeps working. The underlying mailbox state (read/unread, labels) is shared via Exchange, so changes one user makes eventually surface in the other's view after the next sync.

---

Security model

What Workestra can see

When you add support@acme.com as a shared mailbox:

• Everything in that mailbox that your personal Outlook account is allowed to see in Exchange — no more, no less.
• If your admin later narrows your access (e.g. restricts you to a subfolder), Microsoft Graph enforces that at the API level. Workestra inherits whatever Exchange allows.

What Workestra cannot do

• Connect a shared mailbox that you don't have permission on.
• Escalate from Full Access to anything further — Microsoft Graph returns 403 for disallowed operations regardless of what the app tries.
• Reach the shared mailbox if your personal Outlook connection is disconnected or errored.

Audit

Every Graph request Workestra makes is authenticated with your personal Outlook token. From an Exchange audit perspective, all reads and sends on the shared mailbox appear as the acting user (you), not as Workestra. Your admin can trace every action to a specific person in Azure AD sign-in logs.

---

FAQ

Q: Do I need an additional Microsoft 365 license for the shared mailbox? A: No — Microsoft 365 shared mailboxes under 50 GB do not require their own license. This is a Microsoft policy, not a Workestra requirement.

Q: Can the same shared mailbox be connected by multiple users in the same Workestra workspace? A: Yes. Each person's connection is independent.

Q: What happens when the shared mailbox receives a lot of email? A: Real-time webhooks push each new message within seconds. The delta-sync approach means Workestra only pulls new/changed messages, never the whole mailbox again. High-volume support inboxes (thousands of messages per day) are a supported use case.

Q: Can I connect a distribution list instead of a shared mailbox? A: No. A distribution list doesn't have its own mailbox — it just forwards to multiple recipients. Workestra needs a real mailbox with Microsoft Graph endpoints.

Q: Can I restrict which Workestra users can read the shared mailbox? A: Yes, but not in Workestra settings — in Exchange. Only users to whom Exchange has granted Full Access can add the shared mailbox to their Workestra account. Limiting Exchange access limits Workestra access automatically.

Q: If I change my personal email address in Microsoft 365, do my shared mailboxes break? A: Not as long as the user object in Azure AD is the same (most UPN renames preserve this). Exchange re-evaluates permissions based on user identity, not email address. You may need to reconnect your personal Outlook connection after a UPN change, but your shared mailboxes will work once that's done.

---

Next Steps

• Microsoft 365 Integration — Full Outlook setup guide
• Historical backfill — How shared-mailbox history is pulled in
• Inbox — Where shared-mailbox threads appear alongside personal mail and notifications
• Email in your modules — Shared-mailbox threads on Support tickets
• Sending Emails — Composition features, CC/BCC, signatures
• Email Signatures — Separate signatures per connected mailbox