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 #

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 #

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 #

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 #

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 #

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 #

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 #

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 #

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 #

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 #

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#

Beginners: Start with queries 1-3 for basic JMAP patterns
Intermediate: Move to queries 4-6 for complex filtering and threading
Advanced: Study queries 7-9 for multi-method coordination
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)