Mine Mailbox Tool

The Mine Mailbox Tool enables AI agents to autonomously configure and trigger email mining operations. Rather than requiring manual intervention through the Admin Console, agents can programmatically build knowledge bases from email archives based on specific criteria they identify during their operations.

Overview

The Problem

With standard Email Indexing for Search, all knowledge source configuration and scanning requires human intervention:

• Knowledge Source Configuration - Administrators must manually create and configure knowledge sources with mailbox addresses, folder paths, topic filters, and value thresholds
• Scan Triggering - Email scans must be manually started with specific parameters
• No Agent Awareness - Agents have no visibility into when scans complete or what was indexed

This creates limitations for advanced use cases:

• Agents cannot build targeted knowledge bases when they identify information gaps
• SME agents cannot proactively mine relevant email history for research tasks
• Orchestrator agents cannot set up knowledge sources for new team members
• Self-improving systems cannot expand their own knowledge resources autonomously

The Solution

The Mine Mailbox Tool gives agents the ability to:

1. Create new knowledge sources targeting specific mailboxes
2. Update existing knowledge source configurations
3. Trigger email scans with customizable parameters
4. Receive notifications when scans complete with summary statistics
5. Query scan status and check their quota availability

This creates a continuously growing knowledge base, enriched by your AI agents' operational insights about what information is valuable.

Prerequisites

Before agents can use the Mine Mailbox Tool, you need:

1. Email History Index - A provisioned Grounded Knowledge Index of type "Email Archive" (see Grounded Knowledge Index Setup Wizard)
2. Microsoft 365 Integration - Your organization must be connected via Build > Connections > Microsoft 365
3. Feature Enabled - The Mine Mailbox Tool must be enabled in your tenant settings
4. Tool Assignment - Agents must have the mine_mailbox tool assigned to use this capability

Enabling the Tool

Step 1: Navigate to Settings

1. Sign in to Control Bridge
2. Navigate to Build > Knowledge > Mine Mailbox Tool

Step 2: Enable the Feature

The settings page displays an overview of your configuration and usage statistics.

1. Toggle Enable Mine Mailbox Tool to ON
2. The configuration section expands to show rate limit options

Step 3: Configure Rate Limits

Set limits to control agent scanning activity:

Setting	Default	Description
Max Scans per Hour	3	Maximum scans any single agent can trigger per hour
Max Scans per Day	10	Maximum scans any single agent can trigger per day
Max Emails per Scan	1,000	Maximum emails processed per scan operation
Default Require Approval	Enabled	Whether agent-created sources require human approval for indexed emails

tip

Start with the defaults and adjust based on your agents' activity. Conservative limits help prevent runaway costs from excessive LLM calls during email value assessment.

Step 4: Save Settings

Click Save Changes to apply your configuration.

Assigning the Tool to Agents

After enabling the feature, you need to assign the mine_mailbox tool to agents that should have mining capability.

1. Navigate to Build > AI Agents > Agents
2. Edit the agent you want to enable
3. In the Tools section, select Mine Mailbox from the available tools
4. Save the agent configuration

Recommended Agents

Consider enabling this tool for:

Agent Type	Use Case
Research SMEs	Mine mailboxes for domain-specific knowledge to answer queries
Orchestrator Agents	Configure knowledge sources for sub-agents and workflows
Executive Assistant	Build targeted email indexes for investigation tasks
AICOS	Expand organizational knowledge as it identifies information gaps
Onboarding Agents	Set up knowledge sources for new team members automatically

How Agents Use the Tool

When an agent has the mine_mailbox tool assigned, it can perform the following operations:

Operations

Operation	Description	Required Parameters
create_source	Create a new knowledge source	mailboxAddress
update_source	Modify source configuration	sourceId
trigger_scan	Start an email scan	sourceId
get_status	Check scan progress	scanRequestId
list_sources	List agent-created sources	None
get_quota	Check rate limit availability	None

Parameters

Parameter	Type	Description
mailboxAddress	string	Email address of the mailbox to mine (required for create_source)
sourceId	integer	ID of existing knowledge source (required for update_source and trigger_scan)
scanRequestId	integer	ID of a scan request (required for get_status)
sourceName	string	Optional friendly name for the knowledge source
folderPath	string	Specific folder path to scan (e.g., 'Inbox/Projects')
topicFilters	array	Topic taxonomy IDs to filter for
includeKeywords	array	Keywords that must appear in emails to be indexed
excludeKeywords	array	Keywords that exclude emails from indexing
minValueThreshold	number	Minimum value score for indexing (0.5-1.0, default: 0.7)
scanStartDate	string	Only scan emails after this date (YYYY-MM-DD)
maxEmails	integer	Maximum emails to process in this scan (1-1000)
notifyOnComplete	boolean	Receive notification when scan completes (default: true)

Example Agent Prompts

To guide your agents on when to use this tool, consider adding instructions like:

When you identify a gap in your knowledge that could be filled by mining email archives:
1. Check if a relevant knowledge source already exists using list_sources
2. If not, create one targeting the appropriate mailbox with create_source
3. Trigger a scan with appropriate filters (topic, keywords, date range)
4. Wait for completion notification before using the new knowledge

Good candidates for mining:
- When asked about historical client communications
- When researching a project's email trail
- When building expertise for a new domain
- When onboarding requires access to past discussions

Scan Completion Notifications

When an agent triggers a scan with notifyOnComplete: true, they receive a notification when the scan completes. The notification includes:

Field	Description
Status	Success, failed, or cancelled
Emails Scanned	Total emails processed
Emails Evaluated	Emails sent through LLM value assessment
Emails Indexed	Emails that met the value threshold and were indexed
LLM Cost	Cost incurred for value assessment
Duration	How long the scan took

info

The scan completion notifier runs every 2 minutes. Agents may need to wait for the notification before the new knowledge becomes searchable.

Monitoring Usage

Settings Page Statistics

The Mine Mailbox Tool settings page displays real-time usage statistics:

Metric	Description
Agent-Created Sources	Total knowledge sources created by agents
Total Agent Scans	Total scans triggered by agents
Recent Scans	Scans triggered in the last 24 hours
Running Scans	Currently active scans
Unique Agents	Number of distinct agents using this feature

Audit Logs

For detailed analysis, navigate to Manage > Data & Logs > Mine Mailbox Logs (when available).

The logs provide:

Filters

• Agent - Filter by specific agent
• Operation - Filter by operation type (create_source, trigger_scan, etc.)
• Outcome - Filter by result: success, denied, error, quota_exceeded
• Date Range - Filter by start and end dates

Log Details

Click any log entry to view:

• Operation performed
• Agent that performed it
• Parameters used
• Outcome and any error message
• Related source ID or scan request ID
• Timestamp

Security Considerations

The Mine Mailbox Tool includes several security measures:

Measure	Description
Tenant Isolation	Agents can only create sources for mailboxes within their tenant's Microsoft 365 organization
Mailbox Validation	Mailbox access is validated before creating sources
Source Ownership	Agents can only modify sources they created (human-created sources remain editable by any agent)
Rate Limiting	Per-agent hourly and daily limits prevent overwhelming email infrastructure
Email Caps	Maximum emails per scan controls LLM costs
Approval Default	Agent-created sources default to requiring human approval for indexed emails
Audit Trail	All mining operations are logged for compliance
Tool Assignment	Only agents with explicit tool access can mine mailboxes

Quotas and Rate Limits

Agent-Level Quotas

Each agent has individual quotas:

Quota	Default	Description
Hourly Scans	3	Max scans per agent per hour
Daily Scans	10	Max scans per agent per day

Tenant-Level Limits

Limit	Default	Description
Max Emails per Scan	1,000	Global cap on emails processed per scan
Concurrent Agent Scans	2	Maximum simultaneous agent-initiated scans

Quota Exceeded Behavior

When an agent exceeds their quota:

1. The operation is rejected with a quota_exceeded outcome
2. The response includes the current quota status and when it resets
3. The rejection is logged for monitoring
4. The agent can use get_quota to check availability before attempting operations

Troubleshooting

Agent Cannot Create Source

Symptoms: Agent calls fail with "feature not enabled" error

Solutions:

1. Verify the Mine Mailbox Tool is enabled in settings
2. Confirm the agent has the mine_mailbox tool assigned
3. Check that the mailbox address is within the tenant's organization

Quota Exceeded Errors

Symptoms: Scans fail with "quota exceeded" message

Solutions:

1. Check the usage statistics on the settings page
2. Identify which agents are consuming the most quota
3. Consider increasing limits if the scanning is valuable
4. Review agent instructions to reduce unnecessary scans

Scan Doesn't Complete

Symptoms: Scan stays in "running" status for extended time

Solutions:

1. Check Build > Knowledge > Scan Activity for progress
2. Large mailboxes may take longer to process
3. Verify the Microsoft 365 connection is healthy
4. Check for rate limiting from Microsoft Graph API

No Notification Received

Symptoms: Scan completes but agent doesn't receive notification

Solutions:

1. Verify notifyOnComplete was set to true when triggering the scan
2. The notifier runs every 2 minutes; wait and check again
3. Check the scan request status using get_status operation

Source Modification Denied

Symptoms: Agent cannot update a knowledge source

Solutions:

1. Agents can only modify sources they created
2. Check if another agent created the source
3. Human-created sources (via Admin Console) are modifiable by any agent
4. Consider creating a new source instead of modifying existing ones

Best Practices

Source Naming

• Use descriptive source names that identify the purpose
• Include the agent's focus area in the name (e.g., "Sales Research - Acme Corp")
• Avoid duplicate sources by using list_sources first

Scan Parameters

• Start with conservative date ranges (last 6-12 months)
• Use topic filters to focus on relevant content
• Include keywords to target specific subjects
• Set appropriate value thresholds (0.7+ for quality content)

Quota Management

• Use get_quota to check availability before scanning
• Schedule scans during off-peak hours when possible
• Combine related queries into single comprehensive scans
• Monitor daily usage patterns to optimize limits

Agent Instructions

• Provide clear guidance on when mining is appropriate
• Encourage checking for existing sources before creating new ones
• Guide appropriate use of scan parameters
• Remind agents to wait for scan completion before using new knowledge

Relationship to Email Indexing for Search

The Mine Mailbox Tool builds on the same infrastructure as Email Indexing for Search:

Feature	Email Indexing for Search	Mine Mailbox Tool
Initiated By	Administrators via Admin Console	AI Agents via tool calls
Configuration	Manual setup	Programmatic via parameters
Scanning	Manual trigger or scheduled	Agent-triggered on demand
Value Assessment	Same LLM-powered evaluation	Same LLM-powered evaluation
Approval Queue	Shared approval queue	Shared approval queue
Indexing	Same Azure AI Search index	Same Azure AI Search index
Use Case	Systematic knowledge building	Dynamic, context-driven knowledge building

Both features share:

• The Email History Index (Grounded Knowledge Index)
• Value assessment and topic classification
• The approval queue for human review
• The indexed knowledge base searchable by agents

Related Topics

• Email Indexing for Search
• Grounded Knowledge Indexes
• Grounded Knowledge Index Setup Wizard
• Topic Taxonomy
• Index Knowledge Tool
• Tools
• Agents