Microsoft Mail (identos.ms-mail)

User-delegated proxy for the Microsoft Graph Mail API. The signed-in user's own OAuth token (idp_passthrough against a Microsoft Entra IdP) is forwarded to Graph for every call — Outlook's per-user permissions and mailbox boundaries apply naturally.

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.

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

Supported auth modes

Type	Details
idp_passthrough	requires IdP microsoft

Setup fields

ID	Label	Default	Secret?	Notes
upstream_auth.type	Authentication	idp_passthrough	no	—

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.