# JMAP Query Examples for Personal Email Management

This directory contains 10 comprehensive JMAP query examples that demonstrate the full range of the JMAP protocol for personal email management. Each example provides realistic, practical queries that users would actually perform on their email, along with detailed explanations of the JMAP concepts and protocol features involved.

## Overview of Query Examples

### [01. Last Week's Unread Email](01-recent-unread-mail.md)
**Use Case**: Retrieve all unread emails from the past 7 days  
**JMAP Concepts**: Email/query filtering, date ranges, keyword negation, result references  
**Complexity**: Beginner - Basic filtering and sorting patterns

### [02. Apple Mail Orange Flagged Messages](02-apple-mail-orange-flagged.md)  
**Use Case**: Find the oldest message marked with Apple Mail's orange flag  
**JMAP Concepts**: Vendor-specific keywords, ascending sort, Apple Mail extensions  
**Complexity**: Intermediate - Vendor keyword handling and edge cases

### [03. Large Emails with Attachments from This Month](03-large-attachments-recent.md)
**Use Case**: Find storage-heavy emails with attachments larger than 1MB  
**JMAP Concepts**: Size filtering, attachment detection, MIME structure analysis  
**Complexity**: Intermediate - Complex filtering and body structure handling

### [04. Complete Conversation Thread](04-conversation-thread.md)
**Use Case**: Retrieve all emails in a specific conversation thread  
**JMAP Concepts**: Thread/get, email threading, chronological ordering, full content  
**Complexity**: Intermediate - Thread operations and conversation reconstruction

### [05. Draft Emails Needing Attention](05-draft-attention-needed.md)
**Use Case**: Find forgotten draft emails that need completion  
**JMAP Concepts**: Mailbox role discovery, draft management, content analysis  
**Complexity**: Advanced - Multi-step queries and mailbox role handling

### [06. Recent Emails Sent to Company Domain](06-sent-company-domain.md)
**Use Case**: Track outgoing emails to colleagues within company domain  
**JMAP Concepts**: EmailSubmission/query, domain filtering, delivery tracking  
**Complexity**: Advanced - Submission tracking and envelope analysis

### [07. VIP Contacts Marked Important](07-vip-important-contacts.md)
**Use Case**: Find emails from VIP contacts marked as important  
**JMAP Concepts**: Complex OR/AND filtering, contact-based queries, priority management  
**Complexity**: Advanced - Multi-level boolean logic and priority systems

### [08. Current Vacation Response Status](08-vacation-response-status.md)
**Use Case**: Check out-of-office configuration and auto-reply activity  
**JMAP Concepts**: VacationResponse singleton, auto-reply tracking, date validation  
**Complexity**: Advanced - Singleton objects and auto-reply correlation

### [09. Identity Management and Configuration](09-identity-management-setup.md)
**Use Case**: Review all sending identities and their recent usage  
**JMAP Concepts**: Identity/get, signature management, identity-submission correlation  
**Complexity**: Advanced - Identity workflows and professional communication patterns

### [10. Comprehensive Multi-Method Dashboard](10-comprehensive-multi-method.md)
**Use Case**: Complete email dashboard with statistics, recent activity, and system status  
**JMAP Concepts**: Complex result references, batch operations, dashboard aggregation  
**Complexity**: Expert - Multi-method coordination and advanced result reference chains

## JMAP Protocol Coverage

These examples collectively demonstrate:

### Core JMAP Methods (RFC 8620)
- ✅ **Core/echo** - Basic connectivity testing
- ✅ **Email/get** - Object retrieval with property selection
- ✅ **Email/query** - Searching and filtering with complex conditions
- ✅ **Thread/get** - Conversation thread retrieval
- ✅ **Mailbox/get** - Folder information and statistics
- ✅ **Mailbox/query** - Finding mailboxes by role and properties

### Email Extensions (RFC 8621)
- ✅ **EmailSubmission/query** - Tracking sent emails and delivery status
- ✅ **EmailSubmission/get** - Submission details and envelope information
- ✅ **Identity/get** - Sending identity management
- ✅ **VacationResponse/get** - Out-of-office configuration

### Advanced Protocol Features
- ✅ **Result References** - Chaining method results with `#ids` and `resultOf`
- ✅ **Complex Filtering** - Boolean AND/OR logic with nested conditions
- ✅ **Property Selection** - Efficient partial object loading
- ✅ **Sorting and Pagination** - Result ordering and limit handling
- ✅ **Date Range Queries** - Time-based filtering with UTC timestamps
- ✅ **Keyword Management** - Standard and custom keyword handling
- ✅ **Mailbox Roles** - System folder discovery and role-based queries
- ✅ **MIME Structure** - Body part analysis and attachment handling
- ✅ **Batch Operations** - Multiple methods in single requests

## Query Patterns and Techniques

### Filtering Patterns
- **Date Ranges**: `after`/`before` for time-based queries
- **Keyword Logic**: `hasKeyword` with boolean values and negation
- **Size Filtering**: `minSize`/`maxSize` for storage management
- **Domain Matching**: Wildcard patterns like `*@company.com`
- **Mailbox Filtering**: `inMailbox` for folder-specific queries

### Sorting Strategies
- **Chronological**: `receivedAt`/`sentAt` for time-based ordering
- **Priority**: `size` for storage optimization
- **Mixed Ordering**: Ascending vs descending based on use case

### Result Reference Techniques
- **Simple References**: `resultOf` with `path` for ID extraction
- **Array Extraction**: `path: "/ids"` for query result IDs
- **Property Extraction**: `path: "/list/*/threadId"` for object properties
- **Nested References**: Multi-level method dependencies

### Performance Optimization
- **Property Minimization**: Request only needed properties
- **Batch Processing**: Multiple methods in single requests
- **Smart Limits**: Appropriate result set sizes for use cases
- **Parallel Queries**: Independent operations run simultaneously

## Business Use Cases Covered

### Personal Productivity
- Inbox management and unread email processing
- Draft completion and pending communication workflow
- Priority email identification and VIP management
- Storage optimization and attachment management

### Professional Communication
- Identity management for different professional contexts
- Company domain communication tracking
- Vacation response configuration and monitoring
- Meeting and collaboration email management

### System Administration
- Email system health monitoring
- Delivery status tracking and troubleshooting
- Account configuration validation
- Usage pattern analysis and optimization

## Integration Examples

Each query example includes:
- **Complete JMAP JSON requests** that can be used directly
- **Expected response structures** with realistic data
- **Detailed explanations** of each JMAP concept used
- **Business logic applications** for real-world scenarios
- **Advanced variations** for extended functionality
- **Error handling patterns** for robust implementations

## Getting Started

1. **Beginners**: Start with queries 1-3 for basic JMAP patterns
2. **Intermediate**: Move to queries 4-6 for complex filtering and threading
3. **Advanced**: Study queries 7-9 for multi-method coordination
4. **Experts**: Analyze query 10 for comprehensive dashboard implementation

Each query is self-contained and can be understood independently, but they build upon each other to demonstrate increasingly sophisticated JMAP usage patterns.

## Implementation Notes

These examples are designed for the OCaml JMAP library documented in this repository, but the JSON requests and concepts apply to any JMAP implementation. The queries demonstrate best practices for:

- **Type Safety**: Leveraging OCaml's type system for JMAP objects
- **Error Handling**: Proper result validation and error propagation
- **Performance**: Efficient queries that minimize server load
- **Maintainability**: Clear, documented query structures
- **RFC Compliance**: Adherence to JMAP specifications (RFC 8620/8621)

## References

- [RFC 8620: The JSON Meta Application Protocol (JMAP)](https://www.rfc-editor.org/rfc/rfc8620.html)
- [RFC 8621: The JSON Meta Application Protocol (JMAP) for Mail](https://www.rfc-editor.org/rfc/rfc8621.html)
- [JMAP Method Documentation](../jmap/jmap_methods.mli)
- [Email Type Definitions](../jmap-email/email.mli)