EmailOS Watch Command Documentation

The mailos watch command monitors scheduled emails and automatically sends them at their scheduled time.

Quick Start

mailos watch

This starts the scheduler daemon that checks for due emails every minute and sends them automatically.

Command-Line Flags

Usage Examples

Continuous Monitoring

Run the scheduler continuously with default 1-minute interval:

mailos watch

Output:

📬 EmailOS Scheduler Started
   Checking for scheduled emails every 1m0s
   Press Ctrl+C to stop

[12:15:30] Checking for due emails...
   No emails due

[12:16:30] Checking for due emails...

📤 Sending 1 scheduled email(s)...

✅ Sent: Meeting Reminder → [[email protected]]

Custom Check Interval

Check more frequently for time-sensitive emails:

mailos watch --interval 30s

Or check less frequently to save resources:

mailos watch --interval 5m

One-Time Processing

Process all due emails once and exit (useful for cron jobs):

mailos watch --once

Verbose Mode

See detailed SMTP debugging information:

mailos watch --verbose

This shows:

• Detailed check timestamps
• SMTP connection details
• Email sending process
• Error messages if any

Background Execution

Using nohup

Run as a background daemon with logging:

nohup mailos watch --interval 30s > ~/mailos-scheduler.log 2>&1 &

Check if running:

ps aux | grep "mailos watch"

Stop the scheduler:

pkill -f "mailos watch"

Using screen or tmux

Run in a persistent terminal session:

# Using screen
screen -S mailos-scheduler
mailos watch
# Press Ctrl+A then D to detach

# Reattach later
screen -r mailos-scheduler

# Using tmux
tmux new -s mailos-scheduler
mailos watch
# Press Ctrl+B then D to detach

# Reattach later
tmux attach -t mailos-scheduler

Using systemd (Linux)

Create a systemd service for automatic startup:

1. Create service file /etc/systemd/system/mailos-watch.service:

[Unit]
Description=MailOS Email Scheduler
After=network.target

[Service]
Type=simple
User=yourusername
ExecStart=/usr/local/bin/mailos watch --interval 1m
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

2. Enable and start the service:

sudo systemctl enable mailos-watch
sudo systemctl start mailos-watch

# Check status
sudo systemctl status mailos-watch

# View logs
journalctl -u mailos-watch -f

Cron Integration

Use --once flag for cron-based scheduling:

# Edit crontab
crontab -e

# Check every 5 minutes
*/5 * * * * /usr/local/bin/mailos watch --once >> ~/mailos-cron.log 2>&1

# Check every hour
0 * * * * /usr/local/bin/mailos watch --once

# Check every 15 minutes during business hours (9 AM - 5 PM)
*/15 9-17 * * * /usr/local/bin/mailos watch --once

Auto-start on Login

macOS (launchd)

Create ~/Library/LaunchAgents/com.emailos.watch.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.emailos.watch</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/mailos</string>
        <string>watch</string>
        <string>--interval</string>
        <string>1m</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/tmp/mailos-watch.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/mailos-watch-error.log</string>
</dict>
</plist>

Load the service:

launchctl load ~/Library/LaunchAgents/com.emailos.watch.plist
launchctl start com.emailos.watch

# Check status
launchctl list | grep emailos

Shell Startup Files

Add to ~/.zshrc or ~/.bashrc:

# Start mailos watch if not already running
if ! pgrep -f "mailos watch" > /dev/null; then
    nohup mailos watch --interval 30s > /dev/null 2>&1 &
fi

How It Works

1. Initialization: Watch command starts and displays startup message
2. Polling Loop: At each interval:
   • Checks ~/.email/scheduled-emails/ directory
   • Parses JSON files to find emails with scheduled_at <= current_time
   • Sends each due email via SMTP
   • Moves sent email to ~/.email/sent-scheduled/
   • Removes from scheduled queue
3. Continuous: Repeats until stopped with Ctrl+C (unless --once is used)

Error Handling

If an email fails to send:

• Error message is displayed
• Email remains in scheduled queue
• Will be retried on next check interval
• Check logs with --verbose to debug

Common errors:

• Authentication failed: Check account credentials in ~/.email/config.json
• SMTP connection refused: Verify SMTP server settings and network
• Email not found: Email may have been manually deleted from queue

Performance

Resource usage varies with check interval:

• --interval 30s: ~2-3% CPU during checks, negligible between
• --interval 1m: ~1-2% CPU during checks (default)
• --interval 5m: <1% CPU, minimal resource impact

Memory usage: ~20-30 MB regardless of interval

Monitoring

Check scheduler health:

# Process status
ps aux | grep "mailos watch"

# Log file
tail -f ~/mailos-scheduler.log

# Scheduled email count
ls ~/.email/scheduled-emails/ | wc -l

# Recently sent scheduled emails
ls -lt ~/.email/sent-scheduled/ | head -10

Troubleshooting

Emails Not Sending

1. Verify watch is running: ps aux | grep "mailos watch"
2. Check scheduled emails exist: mailos schedule-list
3. Run once with verbose: mailos watch --once --verbose
4. Check account authentication: mailos info

High CPU Usage

• Increase interval: mailos watch --interval 5m
• Check for orphaned processes: pkill -9 -f "mailos watch"
• Verify no infinite loops in error handling

Scheduler Stops Unexpectedly

• Check system logs for crashes
• Run in foreground to see errors: mailos watch --verbose
• Ensure sufficient disk space for logs
• Use systemd or launchd for auto-restart

Related Commands

• mailos send - Schedule emails for future sending
• mailos schedule-list - List all scheduled emails
• Scheduled Sending Guide - Complete scheduling documentation

Files and Directories

Path	Purpose
~/.email/scheduled-emails/	Pending scheduled emails
~/.email/sent-scheduled/	Archive of sent scheduled emails
~/.email/config.json	Account configuration used by watch

Best Practices

1. Run in background: Use screen, tmux, or systemd for persistent operation
2. Monitor logs: Set up log rotation to prevent disk fill
3. Set appropriate intervals: Balance responsiveness with resource usage
4. Use systemd/launchd: For production deployments
5. Health checks: Periodically verify scheduler is running
6. Graceful restarts: Stop before system shutdown to avoid corrupted state