Email OS Docs

Appearance

EmailOS Sync Command ​

The sync command synchronizes your emails from your IMAP server to the local filesystem using mbsync for efficient offline access and local search capabilities.

Usage ​

bash
# Basic sync
mailos sync

# Sync with specific options
mailos sync --limit 500 --verbose

# Sync for specific account
mailos sync --account work@company.com

Features ​

  • Incremental Sync: Only downloads new emails since last sync
  • Folder Organization: Maintains IMAP folder structure locally
  • Attachment Handling: Downloads email attachments for offline access
  • Progress Feedback: Real-time sync progress indicators
  • Configurable Limits: Control how many emails to sync per operation

Command Options ​

Basic Options ​

  • --account string - Email account to use for syncing
  • --dir string - Base directory for storing emails (default: "emails")
  • --limit int - Maximum number of emails to sync per folder (default: 100)

Advanced Options ​

  • --days int - Sync emails from last N days (0 for all) (default: 0)
  • --include-read - Include already read emails in sync
  • --verbose, -v - Show detailed progress information
  • --all - Sync all emails without the 5000 email limit

Examples ​

Basic Sync ​

bash
# Sync latest 100 emails per folder
mailos sync

# Sync with verbose output
mailos sync --verbose

Targeted Sync ​

bash
# Sync last 7 days of emails
mailos sync --days 7

# Sync more emails per folder
mailos sync --limit 500

# Sync everything (no limits)
mailos sync --all

Account-Specific Sync ​

bash
# Sync specific account
mailos sync --account [PERSONAL_ACCOUNT]

# Sync work account with custom directory
mailos sync --account work@company.com --dir work-emails

Local Storage Structure ​

Synced emails are stored in a structured format:

~/.email/
├── received/
│   ├── INBOX/
│   ├── Sent/
│   ├── Drafts/
│   └── [Custom Folders]/
└── config.json

Sync Process ​

  1. Authentication: Connects to your IMAP server
  2. Folder Discovery: Lists all available IMAP folders
  3. Incremental Check: Identifies new emails since last sync
  4. Download: Retrieves email headers, content, and attachments
  5. Local Storage: Saves emails in structured format
  6. Index Update: Updates local search index for fast searching

Requirements ​

mbsync Installation ​

EmailOS uses mbsync for efficient IMAP synchronization:

macOS (Homebrew):

bash
brew install isync

Ubuntu/Debian:

bash
sudo apt-get install isync

CentOS/RHEL/Fedora:

bash
sudo yum install isync

Email Provider Setup ​

  • IMAP Access: Must be enabled in your email provider
  • App Passwords: Required for Gmail, Outlook, etc.
  • SSL/TLS: Secure connection required

Configuration ​

Initial Setup ​

Before first sync, ensure your email account is configured:

bash
# Configure email account
mailos setup

# Verify configuration
mailos config --show

Sync Settings ​

Customize sync behavior in your configuration:

json
{
  "syncSettings": {
    "defaultLimit": 100,
    "includeAttachments": true,
    "syncInterval": "1h",
    "excludeFolders": ["Spam", "Trash"]
  }
}

Performance Tips ​

Optimization Strategies ​

  • Use Limits: Start with smaller limits for initial sync
  • Selective Folders: Exclude unnecessary folders (Spam, Trash)
  • Regular Sync: Run sync regularly to minimize download time
  • Network: Use stable, fast internet for large syncs

Monitoring Progress ​

bash
# Watch sync progress
mailos sync --verbose

# Check sync status
mailos stats --sync

Troubleshooting ​

Common Issues ​

Authentication Errors ​

bash
# Check credentials
mailos config --verify

# Reconfigure account
mailos setup --reconfigure

Sync Failures ​

bash
# Check mbsync availability
mbsync --version

# Reset sync state
mailos sync --reset

# Manual sync with debugging
mailos sync --verbose --debug

Storage Issues ​

bash
# Check disk space
df -h ~/.email

# Clean old emails
mailos cleanup --old-emails

# Compact storage
mailos sync --compact

Error Messages ​

"mbsync not found" ​

Install mbsync using your system package manager (see Requirements).

"IMAP connection failed" ​

  • Verify internet connectivity
  • Check email provider settings
  • Ensure IMAP is enabled
  • Verify app password is correct

"Quota exceeded" ​

  • Check disk space: df -h
  • Use --limit to reduce download size
  • Clean up old emails with mailos cleanup

Security Considerations ​

Data Protection ​

  • Local Encryption: Emails stored in secure format
  • Credential Security: Uses secure credential storage
  • Access Control: File permissions restrict access

Privacy ​

  • Offline Access: No data sent to external servers
  • Local Search: All searching happens locally
  • No Tracking: No usage data collected

Integration with Other Commands ​

Post-Sync Operations ​

bash
# Search synced emails
mailos search "important project"

# Read recent emails
mailos read --limit 10

# Generate email stats
mailos stats --recent

Automation ​

bash
# Add to crontab for regular sync
0 */2 * * * mailos sync --quiet

# Sync before reading
mailos sync && mailos read

Advanced Usage ​

Custom Sync Scripts ​

bash
#!/bin/bash
# Custom sync script

echo "Starting email sync..."
mailos sync --account [PERSONAL_ACCOUNT] --limit 200
mailos sync --account work@company.com --days 7

echo "Generating daily summary..."
mailos stats --today

echo "Sync complete!"

Batch Processing ​

bash
# Sync multiple accounts
for account in [PERSONAL_ACCOUNT] [WORK_ACCOUNT]; do
  mailos sync --account "$account" --verbose
done
  • mailos search - Search through synced emails
  • mailos read - Read emails (works with synced data)
  • mailos stats - View sync and email statistics
  • mailos config - Manage account configuration
  • mailos cleanup - Clean up old synced data

For more information on related commands, see their respective documentation files.

Released under the MIT License.

Copyright © Email OS