Microsoft Outlook (identos.ms-mail)

User-delegated proxy for the Microsoft Graph Mail API. Every call runs as the signed-in user, so Outlook's per-user permissions and mailbox boundaries apply naturally. Two upstream-auth modes are supported:

• entra_refresh (default) — PolicyArc uses the refresh token captured at the user's Microsoft sign-in to mint a fresh, correctly-audienced token per Microsoft service at call time. One sign-in works across any combination of Microsoft connectors — Graph (Mail, OneDrive, Teams) and Azure DevOps together. The minted token is cached per (user, resource) and re-minted on expiry; every call is made as the signed-in user.
• idp_passthrough — forwards the user's Microsoft sign-in token directly to Graph, with no exchange. That sign-in token carries a single audience, so passthrough works for only one Microsoft resource — either Graph (Mail/OneDrive/Teams) or Azure DevOps, not both; don't mix passthrough across Graph and Azure DevOps. Choose this only for strict tenants that disable refresh-token issuance (no offline_access), or that don't want a long-lived refresh token warehoused by PolicyArc. Otherwise prefer entra_refresh.

When to use it

• An agent or workflow needs to read the caller's inbox / search the mailbox / pull attachments.
• An agent needs to send mail as the caller (replies, forwards, or new threads), with the sent message landing in the caller's own Sent Items.
• An operator needs a centralised place to put a read-only kill switch on mailbox mutations during incident response.

What it does NOT do

• No service-account / domain-wide delegation. Microsoft Graph requires per-user OAuth for mailbox writes; there is no shared service account. If you need bulk mailbox ops across users, that's a different deployment shape not covered here.
• No mailbox-wide search across multiple users. Routes are all under /me/... — they only address the signed-in user's mailbox.
• No live MIME assembly. The connector forwards the structured Graph message shape ({subject, body, toRecipients, ...}) verbatim. RFC 822 / EML is not on the wire.

Prerequisites

• One PolicyArc Microsoft IdP (provider key microsoft) configured with the app's client_id/client_secret and the tenant authorize/token endpoints. For the default entra_refresh mode, the login scopes must include offline_access so a refresh token is captured; idp_passthrough does not need it. This is the same IdP Azure DevOps uses — shared, not per-connector. See the Entra ID IdP guide.
• The Entra app granted these delegated Microsoft Graph permissions with admin consent: Mail.Read, Mail.ReadWrite, Mail.Send.
• PBAC_GATEWAY_CREDENTIAL_KEY set on the AS (encrypts the cached tokens).

Install

The connector supports two upstream-auth modes, selected at install time:

• entra_refresh (default) — the gateway uses the refresh token from the user's Microsoft sign-in to mint a Graph-audienced token per call. Works alongside other Microsoft connectors (OneDrive, Teams, Azure DevOps) with a single sign-in.
• idp_passthrough — the user's sign-in token is forwarded to Graph directly. Only works for Graph alone — don't mix it with an Azure DevOps passthrough connector. Reach for this only if your tenant disables refresh-token issuance or you don't want PolicyArc holding a long-lived refresh token; otherwise prefer entra_refresh.

Install from the admin UI (Resources → Add → Microsoft Outlook), choose your auth mode, and click Install. The gateway resolves credentials from the Microsoft IdP registration.

Tool surface (12 tools)

Read paths use the mail:read scope; mutations use mail:write; sends (send_mail, reply_message, forward_message) use mail:send. The autogenerated reference below this README has the full list with route patterns and input schemas.

Operator data

Key	Effect
read_only: true	Denies every non-GET method on this connector. Reads still work; sends, replies, forwards, updates, deletes, moves all return a policy deny.

(Policy rules currently ship in policy/mail.rego but are not yet evaluated by the gateway — connector-owned Rego packages are loaded into OPA but not aggregated into the central decision today. Once aggregation lands, read_only takes effect immediately without a deploy.)

Manifest reference

• ID: identos.ms-mail
• Version: 1.0.0
• Resource type: urn:connector:identos:ms-mail
• Capabilities: mcp

Supported auth modes

Type	Details
entra_refresh	requires IdP microsoft
idp_passthrough	requires IdP microsoft

Setup fields

ID	Label	Default	Secret?	Notes
upstream_auth.type	Authentication	entra_refresh	no	Authentication mode. entra_refresh (default) mints a separate per-resource token for each Microsoft service from your one sign-in, so a single login works across any mix of Microsoft connectors — Graph (Mail/OneDrive/Teams) and Azure DevOps together. idp_passthrough instead forwards your Microsoft sign-in token as-is, and that token is valid for only one audience: passthrough therefore works for either Graph (Mail/OneDrive/Teams) or Azure DevOps, not both. Use entra_refresh if you need more than one.

Scopes

Scope
mail:read
mail:write
mail:send
mail:admin

Routes

Method	Pattern	Scope	Resource template
GET	/v1.0/me/mailFolders/{mailFolder_id}/childFolders	mail:read	mail-folder://{{mailFolder_id}}
GET	/v1.0/me/mailFolders	mail:read	—
GET	/v1.0/me/messages/{message_id}/attachments	mail:read	mail://{{message_id}}
GET	/v1.0/me/messages/{message_id}	mail:read	mail://{{message_id}}
GET	/v1.0/me/messages	mail:read	—
POST	/v1.0/me/sendMail	mail:send	—
POST	/v1.0/me/messages/{message_id}/move	mail:write	mail://{{message_id}}
POST	/v1.0/me/messages/{message_id}/reply	mail:send	mail://{{message_id}}
POST	/v1.0/me/messages/{message_id}/forward	mail:send	mail://{{message_id}}
POST	/v1.0/me/messages	mail:write	—
PATCH	/v1.0/me/messages/{message_id}	mail:write	mail://{{message_id}}
DELETE	/v1.0/me/messages/{message_id}	mail:write	mail://{{message_id}}

MCP tools

Name	Scope	Description
list_subfolders	mail:read	List child folders of a specific mail folder (e.g. subfolders of Inbox, Archive/2025/...). The parent folder is identified by its ID or well-known name (inbox, drafts, sentitems, deleteditems, junkemail, archive).
list_folders	mail:read	List the signed-in user's top-level mail folders (Inbox, Drafts, SentItems, etc.). Use list_subfolders to walk into a specific parent.
list_attachments	mail:read	List the attachments on a specific mail message.
get_message	mail:read	Get a single mail message by its ID.
list_messages	mail:read	List mail messages in the signed-in user's mailbox.
send_mail	mail:send	Send a new mail message immediately. Use create_draft + send for staged sends.
move_message	mail:write	Move a mail message to a different folder.
reply_message	mail:send	Reply to a mail message (to sender only). Supply a comment for a short reply, or override fields via message.
forward_message	mail:send	Forward a mail message to one or more recipients.
create_draft	mail:write	Create a draft mail message in the user's Drafts folder. Use send_mail or the draft's /send endpoint to deliver it later.
update_message	mail:write	Update mutable properties of a mail message (mark as read/unread, set flag, change categories, edit a draft).
delete_message	mail:write	Delete a mail message. The message is moved to Deleted Items (a permanent delete requires the soft-delete endpoint).

Operator data schema

Keys the operator can supply under data.pbac.operator.connectors["identos.ms-mail"].* — consumed by the connector's policy.

Key	Type	Description
read_only	boolean	When true, disables all write and send operations on the mailbox. Read paths (list/get) remain available.