Email Management
Relevant source files
The following files were used as context for generating this wiki page:Email Management in e-zer0 provides a secure, unified interface for AI agents to interact with Gmail and Microsoft Outlook accounts. The system abstracts provider-specific complexities into a standardized set of tools using the Model Context Protocol (MCP). It prioritizes user privacy through active PII redaction, strict audit logging, and a "preview-first" approach to automated filtering.
Sources: README.md:9-25, AGENTS.md:73-77
System Architecture
The email management system functions as a bridge between AI models and third-party email providers. It utilizes Cloudflare Workers for compute and Cloudflare D1 for secure credential storage.
The diagram illustrates the flow of a tool request from an AI agent through the security and abstraction layers to the final email provider APIs.
Sources: AGENTS.md:15-28, src/mcp/server.ts:63-110
Core Functionality
Message Retrieval and Search
The system supports both traditional criteria-based search and semantic natural language search.
- Read Recent Emails: Fetches the most recent messages, automatically indexing them for future semantic queries.
- Advanced Search: Filters emails by folder, read status, sender, subject, and date ranges.
- Semantic Search: Uses Cloudflare Vectorize to find relevant emails based on natural language queries (e.g., "find flight invoices").
Sources: src/mcp/tools.ts:168-220, src/mcp/tools.ts:316-370
Content Sanitization
Every email fetched by an agent passes through a sanitization pipeline. The system redacts sensitive PII, including credit card numbers, SSNs, and API keys. It also evaluates content for prompt injection risks and attaches a security metadata object to each message.
Sources: src/mcp/tools.ts:60-84, README.md:46-55
Unified Organization
The system maps provider-specific organization methods to unified commands.
- Gmail: Uses labels. Moving to a folder adds a specific label and removes the
INBOXlabel. - Outlook: Uses folders. Moving a message physically relocates it and may result in a new
message_id.
Sources: src/mcp/tools.ts:376-390, src/lib/email/gmail.ts:347-380
Security and Governance
Audit Logging
The logAudit function records every action initiated by an agent. Logs include the client identity, the specific action, the target account, success status, and error details.
Sources: src/mcp/tools.ts:40-58
Secure Credential Handling
OAuth tokens are encrypted at rest using AES-256-GCM. The system decrypts tokens only at the time of the API request and never exposes raw credentials to the AI agent or in application logs.
Sources: src/mcp/tools.ts:88-125, AGENTS.md:40-44
Data Protection Policies
- Draft-Only Replies: Agents can create reply drafts but cannot send emails. This ensures a human reviews all outgoing communication.
- Read-Only Calendar: Access to calendar data is strictly read-only; agents cannot create or delete events.
- Grant Isolation: Mailbox access and calendar access require separate, explicit permissions granted by the administrator.
Sources: README.md:89-105, src/mcp/server.ts:605-620
Email Rules and Filters
The system implements a robust mechanism for managing automated email rules. For Gmail, e-zer0 introduces a "Preview-First" workflow to prevent accidental archival of important threads.
| Tool | Provider Support | Description |
|---|---|---|
preview_email_rule | Gmail | Performs a dry-run of a rule against existing mail; returns proposed changes for review. |
apply_email_rule_preview | Gmail | Applies only the specifically reviewed and approved changes from a preview. |
create_email_rule | Unified | Creates a new filter (Gmail) or rule (Outlook) for future incoming mail. |
list_email_rules | Unified | Retrieves all existing automated rules for the account. |
Sources: src/mcp/server.ts:241-285, src/mcp/tools.ts:503-570
Technical Specifications
Data Structures
| Interface | Fields | Source |
|---|---|---|
EmailAccount | id, email_address, provider, status, token_expires_at | src/types.ts:41-53 |
EmailMessage | id, thread_id, subject, from, to, snippet, body, labels | src/lib/email/gmail.ts:10-21 |
AuditLog | client_id, action, target, success, error_message, created_at | src/types.ts:98-107 |
Provider Configuration
Administrators configure providers via the settings UI, which stores encrypted client IDs and secrets in the D1 database.
// Example from src/routes/settings.tsx
settings.post('/google', async (c) => {
const body = await c.req.parseBody();
const clientId = ((body['client_id'] as string) || '').trim();
const clientSecret = ((body['client_secret'] as string) || '').trim();
// Logic to save encrypted settings...
});
Sources: src/routes/settings.tsx:327-345
Summary
Email Management in e-zer0 provides a controlled environment for AI-driven inbox operations. By combining provider abstraction with a heavy emphasis on security—specifically PII redaction, draft-only writes, and detailed auditing—the system allows for powerful automation while maintaining user sovereignty over sensitive data.