# Mail Pro

We understand that our customers need to be confident using Mail Pro, and be aware of our data collection practices. Mail Pro is a Microsoft 365 Copilot declarative agent that helps users manage, search, organize, and gain insights from their email — enabling intelligent email handling, advanced search, prioritization, and communication analysis directly within Microsoft Copilot Chat.

Note

This section is subject to change and we recommend that you check back quarterly for updates.

# Licensing prerequisites

Access requirements

Mail Pro is accessible to users through Microsoft Copilot Chat (available in both free and premium tiers). No additional Copilot license is required beyond the standard Microsoft 365 subscription.

To use Mail Pro, users simply need:

Access to Microsoft Copilot Chat within their Microsoft 365 environment
The Mail Pro agent added to their Copilot Chat instance

Requirement	Scope	Required
Microsoft 365 subscription	Per Mail Pro user	Yes
Copilot Chat access	Per Mail Pro user	Yes
Mail Pro subscription (Microsoft AppSource)	Per tenant	Yes

When a user invokes Mail Pro for the first time, they will be prompted to consent to Mail Pro accessing their mailbox. This consent flow is powered by OAuth 2.0 and allows Mail Pro to:

Read email messages and folder structure
Search across the user's mailbox
Access mailbox settings and preferences

The consent is:

Per-user — each user must consent once on their device
Revocable — users can revoke access at any time through their Azure Entra ID app permissions
Scoped — limited to read-only access (Mail.Read permission; no write/delete permissions)
Delegated — Mail Pro accesses only what the user themselves can access; it respects organizational policies and mailbox sharing permissions

# Data Management Practices

Through the implementation of its different features, Mail Pro accesses, processes and stores several kinds of data:

User profiles
Email messages and metadata (accessed on-demand, not stored durably)
Mail folder structure and labels
Conversation history with the agent
User interaction logs (anonymized)
Marketplace subscription metadata

Here is how we're managing data for these different categories:

Data	Accessed	Cached	Stored	Backup	Notes
User profiles	✔	✔	🚫	🚫	Read at sign-in via Microsoft Graph (`User.Read`). Not persisted beyond the active session.
Email messages	✔	✔	🚫	🚫	Accessed on-demand via Microsoft Graph `/me/messages` and Graph search API. Message content cached in-memory for the active conversation only; never persisted to durable storage.
Mail folder structure	✔	✔	🚫	🚫	Accessed on-demand. Folder names and hierarchy cached in-memory per conversation only. Not stored durably.
Message metadata	✔	✔	🚫	🚫	Sender, recipient, subject, received date accessed for search and filtering. Not persisted beyond the active request.
Search queries	✔	✔	✔	✔	Search expressions and filter patterns stored for analytics and agent optimization. No personally identifiable email content included.
Conversation history	✔	✔	✔	✔	Agent conversation turns stored for audit trail and user history within Copilot. Stored as long as the subscription is active.
User interaction logs	✔	✔	✔	✔	Anonymized logs of user interactions and agent invocations for performance and feature analytics.
Marketplace subscription metadata	✔	✔	✔	✔	Received via Microsoft commercial marketplace SaaS webhooks. Stored for plan, status, and trial tracking.
Copilot Conversations	🚫	🚫	🚫	🚫	No access to other Copilot conversations. No cache. No storage.

No model training

No customer email content is used to train any AI or machine-learning model. Mail Pro only reads from Microsoft Graph mail APIs for user-specific operations and generates responses based on the current conversation context. No email content is sent to any third-party model provider, and no Witivio model is fine-tuned, indexed, or otherwise enriched with customer email data.

# Tenant isolation

Tenant isolation is enforced in the data layer. Every record that belongs to a customer tenant (subscription, conversation history, preferences) carries the caller's tenant context, and every query is filtered by that tenant.

# Microsoft Graph

TIP

All permissions are delegated permissions. Mail Pro operates only on behalf of the authenticated user and cannot access other users' mailboxes.

Scope	Description	Justification	Admin Consent Required
`User.Read`	Retrieve the properties and relationships of the signed-in user.	Allows Mail Pro to read user information and to identify the caller.	No
`Mail.Read`	Read mail in user mailboxes.	Allows Mail Pro to search, retrieve, and display email messages and folders for the authenticated user.	No
`MailboxSettings.Read`	Read user mailbox settings (e.g., focused inbox configuration).	Allows Mail Pro to understand user mailbox preferences and optimize results.	No

TIP

The Microsoft Entra ID App ID is: [To be determined]

# Microsoft Graph endpoints

Each Microsoft Graph endpoint that Mail Pro's agent calls:

Endpoint	Purpose
`GET /v1.0/me/mailFolders`	List mail folders in the user's mailbox.
`GET /v1.0/me/mailFolders/{id}/messages`	Retrieve messages from a specific folder.
`POST /v1.0/me/messages/microsoft.graph.search(query='{query}')`	Search messages using Microsoft Graph KQL syntax.
`GET /v1.0/me/messages?$search="..."`	Search messages by subject, body, sender using KQL.
`GET /v1.0/me/messages/{id}`	Retrieve full message details including body and metadata.

All Graph calls are issued with a token acquired via the on-behalf-of (OBO) flow from the bearer token presented by Microsoft 365 Copilot — Mail Pro never holds an application-only credential and cannot act outside the calling user's permissions.

# Architecture and flow diagram

The agent receives user messages through Copilot Chat, interprets intent via its declarative configuration, invokes the OpenAPI plugin functions with the user's delegated token, queries Microsoft Graph on behalf of the user, and returns results formatted as natural language or Adaptive Cards.

# Copilot Declarative Agent Configuration

Mail Pro exposes its capabilities to Microsoft 365 Copilot as a declarative agent with the following configuration:

# Agent Definition

File: declarativeAgent.json
Schema: Microsoft Copilot declarative agent schema v1.5+
Instructions: LLM instructions defining agent behavior, intent interpretation, query construction patterns
Conversation Starters:
- "Focus my inbox: what's urgent and what can wait?"
- "Summarize my last thread"
- "Summarize key emails since last month"
- "Give me a quick digest of my inbox"
- "List action items from last 10 emails"

# OpenAPI Plugin

File: ai-plugin.json
Schema: Microsoft Copilot plugin schema v2.4+
Namespace: mailpro
Functions exposed: getApiExternalMail (search and retrieve messages)

# Plugin Runtime

Type: OpenAPI
Spec: openapi.yaml (OpenAPI 3.0+ specification)
Authentication: OAuth 2.0 via OAuthPluginVault
- Uses delegated user tokens (on-behalf-of flow)
- No application credentials stored in the plugin
Response Format: Adaptive Cards with email details (subject, summary, sender, date, link)

# Plugin Functions

Function	Description	Input	Output
`getApiExternalMail`	Search and retrieve email messages matching user criteria	Natural language query (converted to Microsoft Graph KQL)	Email list with subject, summary, sender, date, web link

The plugin transforms natural language queries into optimized Microsoft Graph KQL (Keyword Query Language) expressions, handling:

Entity extraction: sender, subject, date range, urgency, read status, attachments
Date interpretation: "last week" → date range, "this month" → date range
Query optimization: minimal filters, cleaned syntax, URL-encoded parameters
Filter cleaning: removes special characters, ensures Graph-compatible syntax

# Trial subscriptions

A tenant on a Microsoft AppSource trial can invoke Mail Pro with the following limitations:

Message retrieval capped at a limited number per query
Search results limited to recent messages (last 30 days)
A banner in responses indicates trial mode and expiration date
Trials run for seven days by default

No data handling differs between trial and paid subscriptions.

# Resource Endpoints

All traffic uses HTTPS protocol on port 443. Here is a short description of each flow:

Name	Comments
`mailpro.teams-pro.com`	Public Mail Pro plugin service endpoint. Accepts OpenAPI calls from Copilot with delegated user tokens.
`graph.microsoft.com`	Microsoft Graph — mail API for message search, retrieval, and folder access.
`login.microsoftonline.com`	Microsoft Entra ID — token acquisition, validation, and on-behalf-of token exchange.
`*.applicationinsights.azure.com`	Application Insights telemetry (optional).
`admin.teams-pro.com`	Admin portal for subscription and configuration management.
`subscriptions.witivio.com`	Subscription validation and licensing.

Both plugin invocation and Microsoft Graph calls operate under the authenticated user's delegated permissions — Mail Pro cannot access content outside that user's mailbox and cannot act with broader permissions than the user holds.

# Security & Compliance

Mail Pro follows Microsoft 365 Copilot agent security and compliance standards:

Delegated permissions only — no application-wide Graph access
On-behalf-of token flow — user tokens exchanged for Graph-scoped tokens at plugin runtime
Tenant isolation — conversation history and preferences scoped to the tenant
GDPR compliant — Azure-hosted in Europe, email content never persisted beyond the active conversation
No external training — email data never sent to external LLM providers or used for model fine-tuning
Adaptive authentication — OAuth tokens refreshed per Microsoft Copilot's lifecycle

← Manager Insights Pro Diagram Maker Pro →