mail2couch/docs

mail2couch Documentation

This directory contains comprehensive documentation for the mail2couch project, which provides two production-ready implementations for backing up mail from IMAP servers to CouchDB.

📚 Documentation Index

Core Documentation

• ANALYSIS.md - Detailed technical analysis of both implementations
• IMPLEMENTATION_COMPARISON.md - Side-by-side comparison of Go vs Rust implementations
• couchdb-schemas.md - CouchDB document schemas and database structure
• TODO.md - Development roadmap and outstanding tasks

Configuration & Setup

• FOLDER_PATTERNS.md - Guide to folder filtering patterns and wildcards
• test-config-comparison.md - Configuration examples and testing scenarios

Examples

• examples/ - Sample CouchDB documents and configuration files
  • sample-mail-document.json - Complete email document with attachments
  • sample-sync-metadata.json - Sync state tracking document
  • simple-mail-document.json - Basic email document structure

🚀 Quick Start

Both implementations are production-ready with identical feature sets:

Go Implementation

cd go && go build -o mail2couch-go .
./mail2couch-go --config ../config.json --dry-run

Rust Implementation

cd rust && cargo build --release
./target/release/mail2couch-rs --config ../config.json --dry-run

✅ Current Status (August 2025)

Both implementations are production-ready with:

• ✅ Full IMAP support with TLS/SSL connections
• ✅ Server-side folder filtering using IMAP LIST patterns
• ✅ Server-side message filtering using IMAP SEARCH with keyword support
• ✅ Binary attachment handling with CouchDB native attachments
• ✅ Incremental synchronization with metadata tracking
• ✅ Sync vs Archive modes for different backup strategies
• ✅ Dry-run mode for safe testing
• ✅ Comprehensive error handling with graceful fallbacks
• ✅ SystemD integration with timer units for automated scheduling
• ✅ Build system integration with justfile for unified project management

🔧 Key Features

Filtering & Search

• Folder Filtering: Wildcard patterns (*, ?, [abc]) with include/exclude lists
• Message Filtering: Subject, sender, and recipient keyword filtering
• IMAP SEARCH: Server-side filtering when supported, client-side fallback
• Date Filtering: Incremental sync based on last sync time or configured since date

Data Storage

• CouchDB Integration: Native attachment storage, per-account databases
• Document Structure: Standardized schema with full email metadata
• Sync Metadata: State tracking for efficient incremental updates
• Duplicate Prevention: UID-based deduplication across syncs

Operations

• Mode Selection: Archive (append-only) or Sync (mirror) modes
• Connection Handling: Automatic retry logic, graceful error recovery
• Progress Reporting: Detailed logging with message counts and timing
• Resource Management: Configurable message limits, connection pooling

📊 Performance & Compatibility

Both implementations have been tested with:

• IMAP Servers: Gmail, Office365, Dovecot, GreenMail
• CouchDB Versions: 3.x with native attachment support
• Message Volumes: Tested with thousands of messages and large attachments
• Network Conditions: Automatic retry and reconnection handling

🛠️ Development

See individual implementation directories for development setup:

• Go: /go/ - Standard Go toolchain with modules
• Rust: /rust/ - Cargo-based build system with comprehensive testing

For unified development commands, use the project justfile:

just build    # Build both implementations
just test     # Run all tests
just check    # Run linting and formatting
just install  # Install systemd services