Grounding Declarative Agents with Email and Shared Mailboxes

Your HR team answers the same onboarding questions every week, and the answers are already sitting in a shared mailbox, buried under 200 unread threads. The Email capability for declarative agents lets you ground your agent directly in mailbox data so it can retrieve, synthesize, and cite real email content. For the Zava Insurance HR Buddy, this means connecting the agent to an Exchange Online mailbox and letting it pull answers from real email conversations.

What the Email Capability Does

The Email capability gives your declarative agent read access to mailbox content (messages, threads, and attachments) so it can answer questions grounded in actual email conversations rather than training data. It works with both personal mailboxes and shared mailboxes, and you can scope it to specific folders. Similar to how the OneDriveAndSharePoint capability connects your agent to document libraries, the Email capability connects it to mailbox data. The platform handles retrieval and synthesis, and your agent returns answers with citations linking back to the original messages.

For Zava Insurance, the HR Buddy can pull answers from the [email protected] shared mailbox, the one that fields every benefits question, equipment request, and “where do I park?” email from new hires.

The Simplest Configuration: Full Mailbox Access

The simplest way to add email grounding is a single capability declaration with no scoping at all:

{
  "capabilities": [
    {
      "name": "Email"
    }
  ]
}

That’s it. The agent now has read access to the current user’s entire personal mailbox. Every user who chats with the agent gets answers grounded in their own mailbox content, with no cross-user data leakage.

This is a great starting point for personal productivity agents. An agent that helps you find action items, summarize threads, or locate that one email from last month? Just add the Email capability and you’re done.

Scoping to Specific Folders

Once you have the basic capability working, you can narrow the scope to specific folders. The folders array accepts well-known folder names like Inbox, SentItems, Drafts, and Archive, custom folder names you’ve created in Exchange, and even Microsoft Graph folder IDs for precise targeting:

{
  "capabilities": [
    {
      "name": "Email",
      "folders": [
        { "folder_id": "Inbox" },
        { "folder_id": "Archive" },
        { "folder_id": "AAMkAGI2TG93AAA=" }
      ]
    }
  ]
}

That last entry uses a Microsoft Graph folder ID, which you can retrieve from the Mail Folder API. This approach works for any folder in any mailbox, including nested folders that might not have unique display names.

Adding a Shared Mailbox

For the HR Buddy scenario, we need something different: a shared mailbox that multiple HR team members can access. Add the shared_mailbox property:

{
  "capabilities": [
    {
      "name": "Email",
      "folders": [
        { "folder_id": "Inbox" },
        { "folder_id": "Support" }
      ],
      "shared_mailbox": "[email protected]"
    }
  ]
}

Now the agent reads from the shared mailbox instead of the user’s personal one. The folders array narrows the scope to just the Inbox and a custom “Support” folder, keeping the agent focused on relevant content rather than indexing every newsletter and auto-reply in the mailbox.

Common Scoping Patterns

A few patterns that work well in production:

• Support agent: scope to Inbox and a custom Escalations folder
• Sales assistant: scope to Inbox and SentItems to capture both inbound and outbound threads
• Project tracker: scope to a custom ProjectAlpha folder where all relevant correspondence lands via inbox rules

The Full Manifest in Context

Here’s how the Email capability fits alongside other knowledge sources in a complete declarativeAgent.json:

{
  "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.6/schema.json",
  "version": "v1.6",
  "name": "HR Buddy",
  "description": "Zava Insurance HR onboarding assistant grounded in SharePoint policies and the shared HR mailbox.",
  "instructions": "$[file('instructions.txt')]",
  "capabilities": [
    {
      "name": "OneDriveAndSharePoint",
      "items_by_url": [
        {
          "url": "https://zavainsurance.sharepoint.com/sites/HR/Shared Documents/Onboarding"
        }
      ]
    },
    {
      "name": "Email",
      "folders": [
        { "folder_id": "Inbox" },
        { "folder_id": "Support" }
      ],
      "shared_mailbox": "[email protected]"
    }
  ]
}

The HR Buddy now draws from both the SharePoint onboarding library and the shared HR mailbox. A new hire asking “What’s the process for ordering a second monitor?” gets an answer synthesized from the official IT Setup Guide in SharePoint and the email thread where IT support walked someone through the exact steps last Tuesday.

Permissions and Access

The Email capability respects Exchange Online permissions. Two rules to know:

1. Personal mailbox: the agent can only access the signed-in user’s own mailbox. No configuration grants cross-user access.
2. Shared mailbox: the user chatting with the agent must have read access to that shared mailbox in Exchange Online. If they don’t, the agent returns nothing from that source.

This is the same permission model your organization already manages. No new admin setup, no additional consent flows. If a user can open the shared mailbox in Outlook, the agent can read from it on their behalf.

Best Practices

Scope narrowly. Don’t give the agent access to an entire shared mailbox with 50,000 messages spanning five years. Scope to the folders that contain the content your agent actually needs. This improves response quality and reduces the chance of surfacing irrelevant or outdated information.

Use inbox rules to curate content. Set up Exchange inbox rules to route relevant emails into dedicated folders, then point the agent at those folders. For the HR Buddy, a rule that moves all emails with “onboarding” or “new hire” in the subject into the Support folder creates a clean, focused dataset.

Combine with other knowledge sources. Email is powerful when paired with SharePoint and Teams grounding. Formal policies live in documents, quick answers live in email threads, and tribal knowledge lives in Teams channels. Layer them together for comprehensive coverage.

Review what’s in the mailbox. Before deploying, skim the folders you’re scoping to. Shared mailboxes often contain auto-forwarded messages, calendar notifications, and other noise. Clean up or reroute what doesn’t belong.

The Value You Just Unlocked

A single capability declaration gave us:

• Instant email intelligence: The agent reads, synthesizes, and cites real mailbox conversations on demand
• Flexible scoping: From full mailbox access (zero config) to pinpointed folders using well-known names or Graph IDs
• Shared mailbox support: One property (shared_mailbox) connects the agent to team-level knowledge that lives in a shared inbox
• Zero infrastructure: No email forwarding rules to a database, no ETL pipeline, no custom Graph API integration
• Built-in security: Exchange Online permissions apply automatically; users only see what they already have access to

The HR Buddy went from answering policy questions from static documents to synthesizing answers from live email threads, combining formal documentation with the real-world context that only exists in mailbox conversations.

Resources

• Declarative Agent Manifest Schema
• Declarative Agents Overview
• Declarative Agent Manifest Schema
• Microsoft 365 Agents Toolkit
• Content Sources for Declarative Agents