Teams do not run support, billing or recruiting from one person’s inbox. They use an
address such as support@acme.com that several people read and answer. An
integration that only connects individual users cannot see that mail.
Microsoft 365 has a mailbox type for the shared address, and Graph can open it. Google Workspace has groups and delegation, and neither is a mailbox you can open as itself. This post covers the mechanics on both sides and how Workwae handles them.
A Microsoft 365 shared mailbox has no user.
A shared mailbox is an Exchange Online mailbox that people open through permissions, not a sign-in. It holds up to 50 GB without a license. The people who use it need their own licensed mailbox, and Microsoft says to keep sign-in blocked for the shared mailbox’s own account (About shared mailboxes in Microsoft 365). So there is no refresh token to store for it. An integration acts through someone or something else.
Graph addresses another mailbox as /users/{id-or-upn} in place of
/me
(Get Outlook messages in a shared or delegated folder).
The path is the same for both kinds of access below.
GET https://graph.microsoft.com/v1.0/users/billing@contoso.com/mailFolders('Inbox')/messages
Authorization: Bearer <token>
POST https://graph.microsoft.com/v1.0/users/billing@contoso.com/sendMail
Authorization: Bearer <token>
Content-Type: application/json
{ "message": { "subject": "Invoice 1042", "toRecipients": [...] } } Delegated or app-only access.
Delegated. A user signs in, and the app asks for
Mail.ReadWrite.Shared and Mail.Send.Shared. The token can then open
the mailboxes that user may open, and neither permission needs admin consent
(Graph permissions reference).
Microsoft also says the .Shared permissions do not support change notification
subscriptions on shared or delegated folders, and points to the application permission
Mail.Read instead (same page).
App-only. A directory administrator consents to application permissions such
as Mail.ReadWrite and Mail.Send. The token acts on any mailbox in the
directory, shared mailboxes included, with no user involved. That is too broad for most
customers, so administrators narrow it. RBAC for Applications in Exchange Online scopes an
app’s permissions to a set of mailboxes, and it replaces Application Access Policies
(RBAC for Applications).
Scoped grants add to the unscoped grants in Microsoft Entra ID, so the app is not restricted
until the Entra grant is removed, and permission changes are cached for 30 minutes to 2 hours.
Send As or Send on Behalf.
Sending depends on which of two Exchange permissions the user holds (Manage permissions for recipients in Exchange Online):
- Send As. The message appears to come from the mailbox. Nothing shows that a delegate sent it.
- Send on Behalf. The From address reads “Delegate on behalf of Mailbox”, and replies go to the mailbox. For shared mailboxes it is set in PowerShell, not in the admin center.
A user with both gets Send As. Neither lets the delegate read the mailbox, which needs Full
Access. In Graph, Mail.Send.Shared sends as the signed-in user, “including
sending on-behalf of others”, and sendMail accepts
/users/{id | userPrincipalName}/sendMail
(user: sendMail).
The Exchange permission decides how the message looks.
Gmail has no shared mailbox type.
A Google Group delivers a copy of each message to its members’ mailboxes. Its web
interface can add Collaborative Inbox features, such as assigning and resolving conversations
(Use a group as a Collaborative Inbox),
but those conversations live in Google Groups. Every Gmail API method names one user’s
mailbox in its userId: an email address, or me
(example: delegates.create).
A group has no mailbox for it to name.
Two Gmail features look like sharing. Both are settings on a user’s mailbox:
- Delegation. A user grants another user in the same Workspace organization
access to their mailbox. The delegate can read, send and delete messages, and their own
address appears when they send. The
users.settings.delegatesresource that manages this requires a service account with domain-wide authority (Manage delegates). It shares a person’s mailbox. It does not make a team mailbox. - Send-as aliases. A mailbox can send with another address in From. Each alias
in
users.settings.sendAshas averificationStatus,acceptedorpending(users.settings.sendAs). Creating one is available only to service account clients with domain-wide authority, and when ownership must be verified, Gmail mails the address and the status stayspending(sendAs.create).
Domain-wide delegation is the server-side route.
With domain-wide delegation, a super administrator authorizes a service account’s client
ID for a list of scopes in the Admin console, and the app names the user to impersonate on each
token request
(Delegate domain-wide authority to the service account).
A team address that is a real user, such as a licensed support@ account, works
like any other mailbox. A group address has no user to impersonate, so an integration has to
pick a member’s mailbox and read the group’s mail out of it.
How Workwae handles it.
Workwae makes each shared address an account of its own, with its own index, sync and events.
The account’s auth.method says how it is reached:
-
shared_mailbox(Microsoft 365, a user’s grant). Connect the user withoptions.sharedMailboxesEnabledoptions.shared_mailboxes_enabled, which addsMail.ReadWrite.SharedandMail.Send.Sharedto the sign-in, then callsharedMailboxes.createshared_mailboxes.create. Workwae reads the inbox with the user’s token first, and a refusal answersshared_mailbox_inaccessible. Requests go to/users/{mailbox}. For an Exchange IMAP delegate the login isuser\shared. -
microsoft_app(app-only). An organization connection holds the application credential, andorgConnections.addAccountsorg_connections.add_accountsadds a shared mailbox by address like any other, after reading its inbox with the app token. -
google_delegation. A Google organization connection holds the service account key, and a mailbox is added by address the same way. -
google_group.orgConnections.addGrouporg_connections.add_groupmakes the group an account read through a member’s mailbox, the relay. It needsgroupsEnabledgroups_enabledon a delegation connection andgmail.settings.sharingauthorized in the Admin console. Workwae adds the group as a send-as alias on the relay, so a send goes out From the group.
import { createClient } from "@workwae/sdk";
const workwae = createClient({ apiKey: process.env.WORKWAE_API_KEY });
// Microsoft 365: the user connected with options.sharedMailboxesEnabled: true.
const billing = await workwae.sharedMailboxes.create({
accountId: userAccountId,
email: "billing@contoso.com",
});
// Microsoft 365 app-only or Google delegation: add by address.
const { items } = await workwae.orgConnections.addAccounts({
connectionId,
mailboxes: [{ email: "support@acme.com" }],
});
// Google Group, read and sent through a member's mailbox.
const group = await workwae.orgConnections.addGroup({
connectionId,
email: "sales@acme.com",
relayEmail: "alex@acme.com",
displayName: "Sales",
});
import os
from workwae import Workwae
workwae = Workwae(api_key=os.environ["WORKWAE_API_KEY"])
# Microsoft 365: the user connected with options.shared_mailboxes_enabled=True.
billing = workwae.shared_mailboxes.create(
account_id=user_account_id,
email="billing@contoso.com",
)
# Microsoft 365 app-only or Google delegation: add by address.
added = workwae.org_connections.add_accounts(
connection_id=connection_id,
mailboxes=[{"email": "support@acme.com"}],
)
# Google Group, read and sent through a member's mailbox.
group = workwae.org_connections.add_group(
connection_id=connection_id,
email="sales@acme.com",
relay_email="alex@acme.com",
display_name="Sales",
)
A group account keeps only the group’s mail from the relay’s mailbox, judged from
headers. A message belongs to the group when Google Groups delivered it, which Workwae reads
from List-Id, or when it was sent as the group from the relay’s own Sent or
Drafts. Workwae creates no filters or labels, and the rest of the relay’s mail is never
downloaded. When a sender’s domain has a DMARC policy, Groups rewrites From to the group
and keeps the sender in X-Original-Sender. Workwae restores the sender only if
Gmail’s Authentication-Results shows the message authenticated for the
group’s domain.
Workwae refuses a group when the connection is not Google domain-wide delegation, when the
group address is the relay’s own, or when the connection lacks
gmail.settings.sharing (group_unsupported, scope_missing).
It also refuses a group in another domain than the relay, because Gmail would hold that alias
pending until the address was verified by mail. If Gmail still reports
pending, the add fails with group_alias_unverified and the alias
Workwae created is removed.
Workwae reads the alias back when a group’s sync starts and before a send, and a passed
check holds for 60 seconds. If an administrator removed the alias, the sync stops with
group_alias_missing and sends fail. Workwae never recreates an alias an
administrator removed. Adding the group again does. Shared mailboxes and groups need the
shared mailboxes module on in the workspace, or the routes answer
plan_module_unavailable.
Limits.
-
There is no Send on Behalf option. Workwae composes a send From the shared address and sets
no
Senderheader, so which permission applies is up to Exchange. Graph does not list Send As grants, so a Microsoft account’s other sender addresses are added as custom identities. Workwae also grants no Exchange permissions, RBAC for Applications included. An administrator does that. -
A shared mailbox opened with a user’s grant depends on that account. Delete the user
and it moves to
reauth_requiredwithdelegate_missing. It cannot be reconnected on its own (shared_mailbox_account). Only an account signed in with its own Microsoft grant can delegate, not Gmail, password IMAP, organization-authenticated or shared mailbox accounts. -
Contacts for a shared mailbox need
Contacts.ReadWrite.Sharedon the delegating grant, or Workwae turns contacts off for it. An IMAP shared mailbox has no calendar. -
Workwae asks Graph for a change subscription on each Microsoft mailbox and polls when Graph
refuses it. Given Microsoft’s note above, expect a mailbox opened with
.Sharedpermissions to be polled rather than pushed. - A group account has no calendar or contacts, shows only the relay’s system folders, and cannot create, rename or delete labels. Mail held for moderation or sent to spam never reaches the members, so it never reaches the account. Another relay means deleting the account and adding the group again, and deleting it leaves the send-as alias on the relay.
- The SDKs are alpha:
@workwae/sdkis 0.1.0-alpha andworkwaeis 0.1.0a2, so their surface can still change.
The organization connections guide covers shared mailboxes and lists the Google Groups requirements and errors. Organization connections describes domain-wide delegation and app-only access, and Microsoft 365 and Gmail cover each provider.