My agentic slop goes here. Not intended for anyone else!
anil.recoil.org
1# JMAP Query Examples for Personal Email Management
2
3This 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.
4
5## Overview of Query Examples
6
7### [01. Last Week's Unread Email](01-recent-unread-mail.md)
8**Use Case**: Retrieve all unread emails from the past 7 days
9**JMAP Concepts**: Email/query filtering, date ranges, keyword negation, result references
10**Complexity**: Beginner - Basic filtering and sorting patterns
11
12### [02. Apple Mail Orange Flagged Messages](02-apple-mail-orange-flagged.md)
13**Use Case**: Find the oldest message marked with Apple Mail's orange flag
14**JMAP Concepts**: Vendor-specific keywords, ascending sort, Apple Mail extensions
15**Complexity**: Intermediate - Vendor keyword handling and edge cases
16
17### [03. Large Emails with Attachments from This Month](03-large-attachments-recent.md)
18**Use Case**: Find storage-heavy emails with attachments larger than 1MB
19**JMAP Concepts**: Size filtering, attachment detection, MIME structure analysis
20**Complexity**: Intermediate - Complex filtering and body structure handling
21
22### [04. Complete Conversation Thread](04-conversation-thread.md)
23**Use Case**: Retrieve all emails in a specific conversation thread
24**JMAP Concepts**: Thread/get, email threading, chronological ordering, full content
25**Complexity**: Intermediate - Thread operations and conversation reconstruction
26
27### [05. Draft Emails Needing Attention](05-draft-attention-needed.md)
28**Use Case**: Find forgotten draft emails that need completion
29**JMAP Concepts**: Mailbox role discovery, draft management, content analysis
30**Complexity**: Advanced - Multi-step queries and mailbox role handling
31
32### [06. Recent Emails Sent to Company Domain](06-sent-company-domain.md)
33**Use Case**: Track outgoing emails to colleagues within company domain
34**JMAP Concepts**: EmailSubmission/query, domain filtering, delivery tracking
35**Complexity**: Advanced - Submission tracking and envelope analysis
36
37### [07. VIP Contacts Marked Important](07-vip-important-contacts.md)
38**Use Case**: Find emails from VIP contacts marked as important
39**JMAP Concepts**: Complex OR/AND filtering, contact-based queries, priority management
40**Complexity**: Advanced - Multi-level boolean logic and priority systems
41
42### [08. Current Vacation Response Status](08-vacation-response-status.md)
43**Use Case**: Check out-of-office configuration and auto-reply activity
44**JMAP Concepts**: VacationResponse singleton, auto-reply tracking, date validation
45**Complexity**: Advanced - Singleton objects and auto-reply correlation
46
47### [09. Identity Management and Configuration](09-identity-management-setup.md)
48**Use Case**: Review all sending identities and their recent usage
49**JMAP Concepts**: Identity/get, signature management, identity-submission correlation
50**Complexity**: Advanced - Identity workflows and professional communication patterns
51
52### [10. Comprehensive Multi-Method Dashboard](10-comprehensive-multi-method.md)
53**Use Case**: Complete email dashboard with statistics, recent activity, and system status
54**JMAP Concepts**: Complex result references, batch operations, dashboard aggregation
55**Complexity**: Expert - Multi-method coordination and advanced result reference chains
56
57## JMAP Protocol Coverage
58
59These examples collectively demonstrate:
60
61### Core JMAP Methods (RFC 8620)
62- ✅ **Core/echo** - Basic connectivity testing
63- ✅ **Email/get** - Object retrieval with property selection
64- ✅ **Email/query** - Searching and filtering with complex conditions
65- ✅ **Thread/get** - Conversation thread retrieval
66- ✅ **Mailbox/get** - Folder information and statistics
67- ✅ **Mailbox/query** - Finding mailboxes by role and properties
68
69### Email Extensions (RFC 8621)
70- ✅ **EmailSubmission/query** - Tracking sent emails and delivery status
71- ✅ **EmailSubmission/get** - Submission details and envelope information
72- ✅ **Identity/get** - Sending identity management
73- ✅ **VacationResponse/get** - Out-of-office configuration
74
75### Advanced Protocol Features
76- ✅ **Result References** - Chaining method results with `#ids` and `resultOf`
77- ✅ **Complex Filtering** - Boolean AND/OR logic with nested conditions
78- ✅ **Property Selection** - Efficient partial object loading
79- ✅ **Sorting and Pagination** - Result ordering and limit handling
80- ✅ **Date Range Queries** - Time-based filtering with UTC timestamps
81- ✅ **Keyword Management** - Standard and custom keyword handling
82- ✅ **Mailbox Roles** - System folder discovery and role-based queries
83- ✅ **MIME Structure** - Body part analysis and attachment handling
84- ✅ **Batch Operations** - Multiple methods in single requests
85
86## Query Patterns and Techniques
87
88### Filtering Patterns
89- **Date Ranges**: `after`/`before` for time-based queries
90- **Keyword Logic**: `hasKeyword` with boolean values and negation
91- **Size Filtering**: `minSize`/`maxSize` for storage management
92- **Domain Matching**: Wildcard patterns like `*@company.com`
93- **Mailbox Filtering**: `inMailbox` for folder-specific queries
94
95### Sorting Strategies
96- **Chronological**: `receivedAt`/`sentAt` for time-based ordering
97- **Priority**: `size` for storage optimization
98- **Mixed Ordering**: Ascending vs descending based on use case
99
100### Result Reference Techniques
101- **Simple References**: `resultOf` with `path` for ID extraction
102- **Array Extraction**: `path: "/ids"` for query result IDs
103- **Property Extraction**: `path: "/list/*/threadId"` for object properties
104- **Nested References**: Multi-level method dependencies
105
106### Performance Optimization
107- **Property Minimization**: Request only needed properties
108- **Batch Processing**: Multiple methods in single requests
109- **Smart Limits**: Appropriate result set sizes for use cases
110- **Parallel Queries**: Independent operations run simultaneously
111
112## Business Use Cases Covered
113
114### Personal Productivity
115- Inbox management and unread email processing
116- Draft completion and pending communication workflow
117- Priority email identification and VIP management
118- Storage optimization and attachment management
119
120### Professional Communication
121- Identity management for different professional contexts
122- Company domain communication tracking
123- Vacation response configuration and monitoring
124- Meeting and collaboration email management
125
126### System Administration
127- Email system health monitoring
128- Delivery status tracking and troubleshooting
129- Account configuration validation
130- Usage pattern analysis and optimization
131
132## Integration Examples
133
134Each query example includes:
135- **Complete JMAP JSON requests** that can be used directly
136- **Expected response structures** with realistic data
137- **Detailed explanations** of each JMAP concept used
138- **Business logic applications** for real-world scenarios
139- **Advanced variations** for extended functionality
140- **Error handling patterns** for robust implementations
141
142## Getting Started
143
1441. **Beginners**: Start with queries 1-3 for basic JMAP patterns
1452. **Intermediate**: Move to queries 4-6 for complex filtering and threading
1463. **Advanced**: Study queries 7-9 for multi-method coordination
1474. **Experts**: Analyze query 10 for comprehensive dashboard implementation
148
149Each query is self-contained and can be understood independently, but they build upon each other to demonstrate increasingly sophisticated JMAP usage patterns.
150
151## Implementation Notes
152
153These 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:
154
155- **Type Safety**: Leveraging OCaml's type system for JMAP objects
156- **Error Handling**: Proper result validation and error propagation
157- **Performance**: Efficient queries that minimize server load
158- **Maintainability**: Clear, documented query structures
159- **RFC Compliance**: Adherence to JMAP specifications (RFC 8620/8621)
160
161## References
162
163- [RFC 8620: The JSON Meta Application Protocol (JMAP)](https://www.rfc-editor.org/rfc/rfc8620.html)
164- [RFC 8621: The JSON Meta Application Protocol (JMAP) for Mail](https://www.rfc-editor.org/rfc/rfc8621.html)
165- [JMAP Method Documentation](../jmap/jmap_methods.mli)
166- [Email Type Definitions](../jmap-email/email.mli)