---
url: /installation.md
---
# Installation Guide
MailOS can be installed through multiple methods depending on your platform and preferences.
## Quick Install
### YOLO Install (Cross-platform)
```bash
# Unix-like systems (macOS, Linux, WSL)
curl -fsSL https://email-os.com/install | bash
# Windows PowerShell (Recommended for Windows)
iwr -useb https://email-os.com/install.ps1 | iex
```
### Package Managers
#### npm (All Platforms)
```bash
npm install -g mailos
```
The npm package automatically downloads the correct binary for your platform (macOS, Linux, Windows) and architecture (x64, ARM64).
#### Windows Package Managers
```bash
# Scoop (Recommended for Windows)
scoop bucket add extras
scoop install extras/mailos
# Chocolatey
choco install mailos
# WinGet (Windows Package Manager)
winget install EmailOS.MailOS
```
#### Unix Package Managers
```bash
# Homebrew (macOS/Linux)
brew tap anduimagui/mailos
brew install mailos
# Arch Linux
paru -S mailos-bin
```
## Platform-Specific Installation
### macOS
#### Apple Silicon (M1/M2/M3/M4)
```bash
curl -L https://github.com/anduimagui/emailos-cli/releases/latest/download/mailos-darwin-arm64.tar.gz | tar xz
sudo mv mailos /usr/local/bin/
```
#### Intel Macs
```bash
curl -L https://github.com/anduimagui/emailos-cli/releases/latest/download/mailos-darwin-amd64.tar.gz | tar xz
sudo mv mailos /usr/local/bin/
```
### Linux
#### x64/AMD64
```bash
curl -L https://github.com/anduimagui/emailos-cli/releases/latest/download/mailos-linux-amd64.tar.gz | tar xz
sudo mv mailos /usr/local/bin/
```
#### ARM64
```bash
curl -L https://github.com/anduimagui/emailos-cli/releases/latest/download/mailos-linux-arm64.tar.gz | tar xz
sudo mv mailos /usr/local/bin/
```
### Windows
#### Using PowerShell
```powershell
# Download the binary
Invoke-WebRequest -Uri "https://github.com/anduimagui/emailos-cli/releases/latest/download/mailos-windows-amd64.tar.gz" -OutFile "mailos.tar.gz"
# Extract (requires tar in Windows 10+)
tar -xzf mailos.tar.gz
# Move to a directory in your PATH
Move-Item mailos.exe "C:\Program Files\mailos\mailos.exe"
# Add to PATH if needed
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";C:\Program Files\mailos", [EnvironmentVariableTarget]::User)
```
#### Using WSL
```bash
# Install the Linux version in WSL
curl -L https://github.com/anduimagui/emailos-cli/releases/latest/download/mailos-linux-amd64.tar.gz | tar xz
sudo mv mailos /usr/local/bin/
```
## Build from Source
### Prerequisites
* Go 1.24 or higher
* Git
### Build Steps
```bash
# Clone the repository
git clone https://github.com/anduimagui/emailos-cli.git
cd emailos-cli
# Build the binary
go build -ldflags="-s -w" -o mailos ./cmd/mailos
# Install globally (Unix-like systems)
sudo mv mailos /usr/local/bin/
# Or add to PATH on Windows
# Move mailos.exe to a directory in your PATH
```
## Verify Installation
After installation, verify MailOS is working:
```bash
# Check version
mailos --version
```
## Next Steps
After successful installation, proceed to:
1. **[Setup Guide](setup.md)** - Configure your email account with app passwords
2. **[Documentation Index](index.md)** - Learn how to use MailOS commands
{/\* TODO: broken link removed — target page `ai-integration.md` does not exist in this repo. Restore once an AI Integration doc is added. \*/}
**Quick Start**: Run `mailos setup` to begin configuration with the interactive setup wizard.
## Email Scheduling Features
MailOS supports advanced email scheduling when **msmtp-queue** is installed:
### Available Scheduling Options
```bash
# Schedule email for specific time
mailos send --to user@example.com --subject "Meeting" --schedule-at "2024-01-01T15:04:05Z"
# Schedule email after a duration
mailos send --to user@example.com --subject "Reminder" --schedule-in "30m"
# Natural language with scheduling
mailos send "thank john@example.com for the meeting" --schedule-in "2h"
# List scheduled emails
mailos send --schedule-list
# Manage scheduled emails
mailos send --schedule-cancel
```
### Installing msmtp-queue Manually
If the automatic installation didn't install msmtp-queue, you can install it manually:
#### macOS (Homebrew)
```bash
# Check if available in Homebrew
brew search msmtp-queue
# Install from source if not available
curl -O https://raw.githubusercontent.com/marlam/msmtp-scripts/master/msmtp-queue/msmtp-queue
chmod +x msmtp-queue
sudo mv msmtp-queue /usr/local/bin/
```
#### Linux
```bash
# Download msmtp-queue scripts
curl -O https://raw.githubusercontent.com/marlam/msmtp-scripts/master/msmtp-queue/msmtp-queue
curl -O https://raw.githubusercontent.com/marlam/msmtp-scripts/master/msmtp-queue/msmtp-runqueue.sh
curl -O https://raw.githubusercontent.com/marlam/msmtp-scripts/master/msmtp-queue/msmtp-listqueue.sh
# Make executable and install
chmod +x msmtp-queue msmtp-runqueue.sh msmtp-listqueue.sh
sudo mv msmtp-queue msmtp-runqueue.sh msmtp-listqueue.sh /usr/local/bin/
```
#### Verify Installation
```bash
# Check if msmtp-queue is available
msmtp-queue --help
mailos send --schedule-list
```
## Updating MailOS
### Using npm
```bash
npm update -g mailos
```
### Using Direct Download
Re-run the installation commands above to get the latest version.
### Check Current Version
```bash
mailos --version
```
## Complete Uninstallation
⚠️ **Important**: Standard uninstallation methods only remove the EmailOS binary, but leave your configuration and email data intact in the `~/.email` directory.
### Quick Complete Uninstallation (Recommended)
Use EmailOS's built-in uninstall command for complete removal:
```bash
# Complete uninstallation with backup
mailos uninstall --backup
# Force uninstallation without prompts
mailos uninstall --force
# See what would be removed (dry run)
mailos uninstall --dry-run
# Keep emails but remove configuration
mailos uninstall --keep-emails
# Keep configuration but remove emails
mailos uninstall --keep-config
```
### Package Manager Uninstallation
#### npm
```bash
npm uninstall -g mailos
```
📝 **Note**: The npm uninstall script will detect your EmailOS data and offer to remove it interactively.
#### Homebrew
```bash
brew uninstall mailos
```
⚠️ **Important**: After Homebrew uninstallation, run `mailos cleanup` to remove remaining data.
#### Manual Binary Removal
```bash
# Unix-like systems
sudo rm /usr/local/bin/mailos
# Windows
# Remove mailos.exe from wherever you installed it
```
⚠️ **Important**: After manual removal, your data remains in `~/.email`. See cleanup instructions below.
### Cleaning Up After Package Manager Uninstallation
If you uninstalled EmailOS using a package manager but want to remove all data:
#### Automatic Cleanup (Recommended)
```bash
# If mailos command is still available
mailos cleanup
# If you get "command not found", manually download and run:
curl -L https://github.com/anduimagui/emailos-cli/releases/latest/download/mailos-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m).tar.gz | tar xz
./mailos cleanup
rm ./mailos
```
#### Manual Cleanup
```bash
# ⚠️ This will permanently delete all EmailOS data!
# Create backup first (optional):
cp -r ~/.email ~/Downloads/emailos-backup-$(date +%Y%m%d)
# Remove EmailOS data directory
rm -rf ~/.email
# Remove any local project configurations
find ~/projects -name ".email" -type d -exec rm -rf {} + 2>/dev/null
```
### What Gets Removed
When performing complete uninstallation, the following are removed:
📁 **Configuration Files**:
* `~/.email/config.json` - Account settings and credentials
* `~/.email/.license` - License information
📧 **Email Data**:
* `~/.email/sent/` - All sent email copies
* `~/.email/received/` - All synced received emails
* `~/.email/drafts/` - All draft emails
🗂️ **Local Project Configs**:
* `.email/` directories in project folders (if any)
🔧 **System Integration**:
* `EMAILOS.md` files in project directories
### Data Recovery
If you uninstalled EmailOS but want to recover your data:
```bash
# Check if data still exists
ls -la ~/.email
# If data exists, reinstall EmailOS to access it
npm install -g mailos
# Or manually backup the data
cp -r ~/.email ~/emailos-backup-$(date +%Y%m%d)
```
### Verification
To verify complete removal:
```bash
# Check for remaining files
ls -la ~/.email 2>/dev/null || echo "✓ No EmailOS data found"
# Check for remaining binary
which mailos 2>/dev/null || echo "✓ No EmailOS binary found"
# Check for local configs (optional)
find ~ -name ".email" -type d 2>/dev/null
```
### Troubleshooting Uninstallation
#### "Permission Denied" Errors
```bash
# If you get permission errors removing ~/.email
sudo rm -rf ~/.email
# If you get permission errors removing the binary
sudo rm $(which mailos)
```
#### Partial Uninstallation Recovery
If uninstallation was interrupted:
```bash
# Reinstall EmailOS temporarily
npm install -g mailos
# Complete the uninstallation
mailos uninstall --force
# Remove the binary again
npm uninstall -g mailos
```
#### Orphaned Data Detection
EmailOS automatically detects orphaned data and will show hints when you run other commands. To manually check:
```bash
# If EmailOS is installed
mailos cleanup
# If EmailOS is not installed but you suspect data remains
ls -la ~/.email
```
## System Requirements
### Minimum Requirements
* **Operating System**: macOS 10.15+, Linux (glibc 2.17+), Windows 10+
* **Memory**: 512MB RAM
* **Storage**: 50MB free space
* **Network**: Internet connection for email operations
### Required Dependencies
MailOS requires the following dependencies for full functionality:
#### Core Dependencies (Required)
* **isync (mbsync)**: For email synchronization
* **msmtp**: For email sending
* **curl** or **wget**: For downloading updates
#### Optional Dependencies
* **msmtp-queue**: For email scheduling features (highly recommended)
The installation script automatically installs these dependencies on supported platforms.
### Supported Email Providers
* Gmail
* Fastmail
* Zoho Mail
* Outlook/Hotmail
* Yahoo Mail
* iCloud Mail (@icloud.com, @me.com, @mac.com)
* ProtonMail (SMTP sending only, requires SMTP token or Bridge)
* Any IMAP/SMTP compatible provider
**Note**: See the [Setup Guide](setup.md) for provider-specific app password instructions.
## Troubleshooting
### Permission Denied (Unix-like systems)
If you get a permission error when moving to `/usr/local/bin/`:
```bash
# Create the directory if it doesn't exist
sudo mkdir -p /usr/local/bin
# Move with sudo
sudo mv mailos /usr/local/bin/
# Make executable
sudo chmod +x /usr/local/bin/mailos
```
### Command Not Found
If `mailos` is not found after installation:
1. **Check if it's in PATH**:
```bash
echo $PATH
which mailos
```
2. **Add to PATH** (bash/zsh):
```bash
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```
3. **For Windows**, ensure the installation directory is in your PATH environment variable.
### npm Installation Issues
The npm package automatically installs the correct binary for your platform during the postinstall phase.
If npm installation fails:
1. **Update npm and Node.js**:
```bash
npm install -g npm@latest
# Ensure Node.js 14.0.0 or higher is installed
node --version
```
2. **Clear npm cache**:
```bash
npm cache clean --force
```
3. **Use sudo (Unix-like systems)**:
```bash
sudo npm install -g mailos
```
4. **Check npm prefix**:
```bash
npm config get prefix
```
5. **Platform-specific binary not found**:
If the postinstall script fails to find a binary for your platform:
```bash
# Check your platform details
node -e "console.log(process.platform, process.arch)"
# Supported platforms: darwin-x64, darwin-arm64, linux-x64, linux-arm64, win32-x64
```
6. **Manual binary installation**:
If npm installation continues to fail, use the direct download method above.
### License Key Issues
If you encounter license validation errors:
1. Ensure you have an active internet connection
2. Check if your license key is valid
3. Visit https://email-os.com/checkout to purchase or renew
4. Run `mailos setup` to re-enter your license key
## Getting Help
* **Documentation**: https://github.com/anduimagui/emailos-cli/tree/main/docs
* **Issues**: https://github.com/anduimagui/emailos-cli/issues
* **Website**: https://email-os.com
## Next Steps
After installation, proceed to:
1. **[Setup Guide](setup.md)** - Configure your email account with app passwords
2. **[Documentation Index](index.md)** - Learn how to use MailOS
{/\* TODO: broken link removed — target page `ai-integration.md` does not exist in this repo. Restore once an AI Integration doc is added. \*/}
**Quick Start**: Run `mailos setup` to begin configuration with the interactive setup wizard.
---
---
url: /setup.md
---
# EmailOS Setup Command Documentation
The `mailos setup` command provides a guided wizard for initial EmailOS configuration, setting up your email account for the first time.
## Basic Usage
```bash
mailos setup
```
Launches the interactive setup wizard.
## Setup Process
### Step 1: Welcome
* Introduction to EmailOS
* Overview of setup process
* Requirements checklist
### Step 2: Email Provider Selection
Choose from supported providers:
* Gmail
* Outlook/Hotmail
* Yahoo Mail
* iCloud Mail
* ProtonMail
* Fastmail
* Custom (manual configuration)
### Step 3: Email Credentials
Enter your:
* Email address
* App-specific password (not regular password)
### Step 4: Test Connection
Automatic testing of:
* SMTP connection (sending)
* IMAP connection (receiving)
* Credential validation
### Step 5: Optional Configuration
* Display name
* Custom sender address
* AI provider selection (claude-code, openai, gemini, etc.)
* Profile image (used in email templates with {{PROFILE\_IMAGE}})
* Interactive mode preference
### Step 6: Confirmation
* Review settings
* Save configuration
* Create README file
## App Password Setup
Most email providers require app-specific passwords when using third-party applications like MailOS. These are special passwords that allow secure access without exposing your main account password.
**When you need app passwords:**
* When MailOS asks for your email password during setup
* If you see authentication errors when trying to send/receive emails
* When your email provider has two-factor authentication enabled
**Important**: Use the generated app password (not your regular email password) when configuring MailOS.
### Gmail App Passwords
**Requirements**: Two-factor authentication must be enabled on your Google account.
**Setup**:
1. Visit: https://myaccount.google.com/apppasswords
2. Select "Mail" from the app dropdown
3. Select your device type
4. Click "Generate" to create a 16-character app password
5. Use this password (not your regular Google password) when setting up MailOS
6. Enable IMAP:
* Gmail Settings → Forwarding and POP/IMAP
* Enable IMAP
**Guide**: https://support.google.com/mail/answer/185833
### Fastmail App Passwords
**Setup**:
1. Visit: https://app.fastmail.com/settings/security/apps
2. Click "New App Password"
3. Enter a name for the application (e.g., "MailOS")
4. Click "Generate password"
5. Copy the generated password for use with MailOS
**Guide**: https://www.fastmail.help/hc/en-us/articles/360058752854-App-passwords
### Outlook/Hotmail App Passwords
**Requirements**: Two-factor authentication must be enabled on your Microsoft account.
**Setup**:
1. Visit: https://account.live.com/proofs/AppPassword
2. Click "Create a new app password"
3. Copy the generated 16-character password
4. Use this password when configuring MailOS
**Guide**: https://support.microsoft.com/en-gb/account-billing/how-to-get-and-use-app-passwords-5896ed9b-4263-e681-128a-a6f2979a7944
### Yahoo Mail App Passwords
**Requirements**: Two-factor authentication must be enabled on your Yahoo account.
**Setup**:
1. Visit the Yahoo app password generation page: https://login.yahoo.com/myaccount/security/app-password-generate
2. Enter a name for the app (e.g., "MailOS")
3. Click "Generate password"
4. Copy the 16-character code (you'll only see this once)
5. Use this password when configuring MailOS
**Direct link**: https://login.yahoo.com/myaccount/security/app-password-generate
**Guide**: https://help.yahoo.com/kb/SLN15241.html
### Zoho Mail App Passwords
**Requirements**: Two-factor authentication must be enabled on your Zoho account.
**Setup**:
1. Sign in to https://accounts.zoho.com
2. Go to My Account → Security → App Passwords
3. Click "Generate New Password"
4. Enter a name for the application
5. Click "Generate"
6. Copy the 16-character password (displayed only once)
**Additional**: Ensure IMAP is enabled in your Zoho Mail settings under Mail Accounts → IMAP.
### iCloud Mail App Passwords
**Requirements**: Two-factor authentication must be enabled on your Apple ID account.
**Setup**:
1. Visit: https://appleid.apple.com/account/manage
2. Sign in with your Apple ID
3. Go to "Security" section
4. Under "App-Specific Passwords", click "Generate Password..."
5. Enter a label for the password (e.g., "EmailOS")
6. Click "Create"
7. Copy the generated 16-character password (shown only once)
8. Use this password when configuring MailOS
**Guide**: https://support.apple.com/HT204397
**Note**: iCloud Mail supports @icloud.com, @me.com, and @mac.com email addresses.
### ProtonMail Setup
ProtonMail integration requires special setup due to its security architecture. EmailOS currently supports SMTP-only sending for ProtonMail.
#### Option 1: SMTP Token (Custom Domains Only)
For custom domain emails hosted on ProtonMail:
1. **Generate SMTP Token**:
* Log into your ProtonMail account
* Go to Settings > Security
* Generate an SMTP submission token for your custom domain
* **Note**: This only works with custom domains, not @proton.me addresses
2. **Configure EmailOS**:
```bash
mailos setup --provider=protonmail --email=[YOUR_CUSTOM_DOMAIN]
```
* Use your custom domain email address
* Enter the SMTP token as the password when prompted
#### Option 2: ProtonMail Bridge (Full Integration)
For complete IMAP/SMTP access including @proton.me addresses:
1. **Requirements**:
* ProtonMail Plus, Professional, or Visionary subscription
* ProtonMail Bridge desktop application
2. **Install Bridge**:
* Download from: https://proton.me/mail/bridge
* Install and set up with your ProtonMail credentials
* Bridge creates local IMAP/SMTP servers
3. **Configure EmailOS**:
```bash
# Auto-detects ProtonMail provider from @proton.me domain
mailos setup --email=[YOUR_PROTON_ADDRESS]
# Or explicitly specify provider
mailos setup --provider=protonmail --email=[YOUR_PROTON_ADDRESS]
```
* EmailOS automatically detects ProtonMail from @proton.me, @protonmail.com, and @protonmail.ch domains
* Use the Bridge-generated password (not your ProtonMail password)
* Bridge must be running for email operations
#### Limitations
* **SMTP Only**: Current implementation supports sending emails only
* **No IMAP**: Email reading/syncing not supported yet
* **Bridge Dependency**: Full features require ProtonMail Bridge for @proton.me addresses
## Automatic Provider Detection
EmailOS can automatically detect your email provider based on your email domain, simplifying the setup process.
### Supported Auto-Detection
When you provide only an email address, EmailOS will automatically detect:
* **Gmail**: `@gmail.com`, `@googlemail.com`
* **Fastmail**: `@fastmail.com`, `@fm.fastmail.com`
* **Outlook/Hotmail**: `@outlook.com`, `@hotmail.com`, `@live.com`
* **Yahoo Mail**: `@yahoo.com`, `@yahoo.co.uk`, etc.
* **Zoho Mail**: `@zoho.com`, `@zohomail.com`
* **iCloud Mail**: `@icloud.com`, `@me.com`, `@mac.com`
* **ProtonMail**: `@proton.me`, `@protonmail.com`, `@protonmail.ch`
### Usage Examples
```bash
# Auto-detects Gmail
mailos setup --email=[GMAIL_ADDRESS]
# Auto-detects ProtonMail
mailos setup --email=[PROTON_ADDRESS]
# Auto-detects Fastmail
mailos setup --email=[FASTMAIL_ADDRESS]
# Auto-detects iCloud Mail
mailos setup --email=[ICLOUD_ADDRESS]
# Manual override (if auto-detection is incorrect)
mailos setup --email=[CUSTOM_DOMAIN_ADDRESS] --provider=fastmail
```
### Custom Domain Detection
For custom domains, EmailOS attempts to detect the provider using:
1. **MX Record Analysis**: Checks DNS MX records for provider signatures
2. **Domain Patterns**: Looks for known hosting patterns
3. **Fallback**: Defaults to Fastmail for unknown custom domains
### Interactive Confirmation
When auto-detection occurs, you'll see:
```
✓ Auto-detected provider: ProtonMail (SMTP Only) (via domain)
Use this provider? (Y/n):
```
You can accept the detection or choose to select manually.
## Custom Provider Setup
For unlisted providers, you'll need:
### Required Information
* SMTP server hostname
* SMTP port (usually 587, 465, or 25)
* SMTP security (TLS/SSL/None)
* IMAP server hostname
* IMAP port (usually 993 or 143)
* IMAP security (TLS/SSL/None)
### Common Settings
| Provider | SMTP Server | SMTP Port | IMAP Server | IMAP Port |
|----------|------------|-----------|-------------|-----------|
| Gmail | smtp.gmail.com | 587 | imap.gmail.com | 993 |
| Outlook | smtp-mail.outlook.com | 587 | outlook.office365.com | 993 |
| Yahoo | smtp.mail.yahoo.com | 587 | imap.mail.yahoo.com | 993 |
| iCloud | smtp.mail.me.com | 587 | imap.mail.me.com | 993 |
## First-Time Setup
### Prerequisites
1. Email account with IMAP enabled
2. 2FA enabled (recommended)
3. App-specific password generated
4. Internet connection
### Quick Start
```bash
# Install EmailOS (if not already installed)
npm install -g @emailos/mailos
# Run setup
mailos setup
# Follow the prompts
```
### Verification
After setup, verify with:
```bash
# Check configuration
mailos info
# Test email reading
mailos read -n 1
# Test email sending
mailos send --to [TEST_RECIPIENT] --subject "Test" --body "Test message"
```
## Configuration Files
Setup creates:
### Global Configuration
`~/.email/config.json`
* Main configuration file
* Encrypted credentials
* Provider settings
### README File
`~/.email/README.md`
* Configuration documentation
* Troubleshooting guide
* Security notes
### Directory Structure
```
~/.email/
├── config.json # Main configuration
├── README.md # Documentation
├── template.html # Email template (optional)
├── .slash_config.json # Slash command preferences
└── cache/ # Email cache (created on use)
```
## Security Considerations
### Password Security
* Never use your main account password
* Always use app-specific passwords
* Passwords are stored locally only
* File permissions set to 600 (owner only)
### Best Practices
1. Enable 2FA on email account
2. Use unique app passwords
3. Regularly rotate passwords
4. Don't share configuration files
5. Add `.email/` to `.gitignore`
## Troubleshooting Setup
### Common Issues
#### "Authentication Failed"
* Verify app password is correct
* Check 2FA is enabled
* Ensure IMAP/SMTP is enabled
* Try regenerating app password
#### "Connection Timeout"
* Check internet connection
* Verify firewall settings
* Try different ports
* Check VPN/proxy settings
#### "Invalid Provider"
* Use exact provider name
* Check spelling
* Use "custom" for unlisted providers
#### "Permission Denied"
* Check file permissions
* Ensure write access to home directory
* Run without sudo
### Reset Configuration
```bash
# Remove existing configuration
rm -rf ~/.email
# Run setup again
mailos setup
```
### Manual Configuration
If setup fails, create manually:
```bash
mkdir -p ~/.email
cat > ~/.email/config.json << 'EOF'
{
"provider": "gmail",
"email": "[YOUR_GMAIL_ADDRESS]",
"password": "your-app-password"
}
EOF
chmod 600 ~/.email/config.json
```
## Multiple Accounts
### Primary Account
```bash
mailos setup
# Sets up global default account
```
### Secondary Accounts
```bash
# Create project-specific configuration
cd my-project
mailos configure --local
```
### Account Switching
```bash
# Use global account
mailos read
# Use local account (in project directory)
cd my-project
mailos read
```
## Advanced Setup Options
### Environment Variables
Override setup with environment:
```bash
export MAILOS_PROVIDER=gmail
export MAILOS_EMAIL=user@gmail.com
export MAILOS_PASSWORD=app-password
mailos setup
```
### Automated Setup
For scripted installation:
```bash
mailos setup --non-interactive \
--provider gmail \
--email user@gmail.com \
--password "app-password"
```
### Import Configuration
```bash
# Copy from another machine
scp other-machine:~/.email/config.json ~/.email/
chmod 600 ~/.email/config.json
```
## Post-Setup
### Recommended Next Steps
1. Test email reading: `mailos read -n 5`
2. Configure template: `mailos template`
3. Create local config: `mailos local`
### Useful Commands
```bash
# View configuration
mailos info
# Configure AI provider
mailos provider
# Test email system
mailos test
# Read recent emails
mailos read
mailos read --json # JSON output
# Send test email
mailos send --to me@example.com --subject "Test" --body "Hello"
mailos send --plain --file message.txt # Send plain text from file
# Interactive mode
mailos interactive # Classic UI
mailos chat # AI chat interface
# View email statistics
mailos stats --days 30 # With visual charts
```
## Migration from Other Clients
### From Gmail Web
* Export is not needed
* EmailOS connects directly via IMAP
* All emails remain on server
### From Outlook
* No migration needed
* Uses existing email account
* Maintains folder structure
### From Thunderbird
* Copy SMTP/IMAP settings
* Use same app password
* Folders sync automatically
## Getting Help
### Resources
* Documentation: `mailos help`
* GitHub Issues: https://github.com/anduimagui/emailos
* Community Forum: https://email-os.com/forum
### Support Commands
```bash
# Check system
mailos test
# View logs
mailos --debug
# Get version
mailos --version
```
---
---
url: /configure.md
---
# EmailOS Configure Command Documentation
The `mailos configure` command manages email account configuration with support for both global and local (project-specific) settings.
## Basic Usage
```bash
mailos configure
```
Interactive configuration wizard for setting up or modifying email settings.
## Command-Line Flags
### Configuration Scope
| Flag | Description | Default | Example |
|------|-------------|---------|---------|
| `--local` | Create/modify project-specific configuration | false | `mailos configure --local` |
| `--quick` | Quick configuration menu | false | `mailos configure --quick` |
### Direct Configuration
| Flag | Description | Example |
|------|-------------|---------|
| `--email` | Email address to configure | `--email john@example.com` |
| `--provider` | Email provider | `--provider gmail` |
| `--name` | Display name for emails | `--name "John Smith"` |
| `--from` | From email address (sender) | `--from noreply@company.com` |
| `--image` | Profile image path | `--image /path/to/profile.jpg` |
| `--ai` | AI CLI provider | `--ai claude-code` |
| `--signature` | Path to email signature HTML file | `--signature /path/to/signature.html` |
## Configuration Types
### Global Configuration
Located at `~/.email/config.json`
* Used by default for all EmailOS commands
* Shared across all projects
* Contains full email credentials
### Local Configuration
Located at `./.email/config.json`
* Project-specific settings
* Inherits from global configuration
* Override specific fields like display name or from address
* Automatically added to `.gitignore`
## Configuration Inheritance
Local configs inherit from global settings:
```
Global Config (~/. email/):
- provider: gmail
- email: john@example.com
- password: ****
- from_name: John Smith
Local Config (./.email/):
- from_name: Project Bot # Overrides global
- from_email: bot@project.com # Project-specific sender
```
## Supported Providers
| Provider | Configuration Key | Notes |
|----------|------------------|-------|
| Gmail | `gmail` | Requires app-specific password |
| Outlook | `outlook` | Includes Hotmail, Live.com |
| Yahoo | `yahoo` | Requires app password |
| iCloud | `icloud` | Apple Mail |
| ProtonMail | `proton` | Bridge required |
| Fastmail | `fastmail` | App password recommended |
| Custom | `custom` | Manual SMTP/IMAP settings |
## AI CLI Providers
| Provider | Key | Description |
|----------|-----|-------------|
| Claude Code | `claude-code` | Claude via VS Code |
| Claude Yolo | `claude-code-yolo` | Claude without confirmations |
| OpenAI | `openai` | ChatGPT integration |
| Gemini | `gemini` | Google AI |
| OpenCode | `opencode` | Open source alternative |
| None | `none` | Disable AI features |
## Interactive Mode
Running `mailos configure` without flags starts interactive setup:
1. **Provider Selection**: Choose your email service
2. **Email Address**: Enter your email
3. **App Password**: Enter app-specific password
4. **Display Name**: Optional sender name
5. **Profile Image**: Optional profile image path
6. **From Email**: Optional custom sender address
7. **Signature**: Optional HTML signature file path
8. **AI Provider**: Select AI integration
## Quick Configuration
```bash
mailos configure --quick
```
Provides a menu for quick changes:
* Update password
* Change display name
* Switch AI provider
* Modify from address
* Update signature
## Examples
### Initial Setup
```bash
mailos configure
# Follow interactive prompts
```
### Create Local Configuration
```bash
mailos configure --local
# Creates .email/config.json in current directory
```
### Direct Configuration
```bash
mailos configure \
--email john@gmail.com \
--provider gmail \
--name "John Smith" \
--ai claude-code
```
### Project-Specific Sender
```bash
# In project directory
mailos configure --local \
--from noreply@project.com \
--name "Project Notifications"
```
### Set Email Signature
```bash
# Set a global default signature
mailos configure --signature /Users/john/signatures/work.html
# Or set via environment file
echo "MAILOS_SIGNATURE=/path/to/signature.html" >> ~/.email/.env
```
### Update Password Only
```bash
mailos configure --quick
# Select "Update Password" from menu
```
## App Passwords
Most providers require app-specific passwords:
### Gmail
1. Enable 2-factor authentication
2. Go to Google Account settings
3. Security → 2-Step Verification → App passwords
4. Generate password for "Mail"
### Outlook/Hotmail
1. Enable two-step verification
2. Go to Security settings
3. Advanced security → Create app password
### Yahoo
1. Enable two-step verification
2. Account Security → Generate app password
3. Select "Other App" and name it
### iCloud
1. Enable two-factor authentication
2. Sign in to Apple ID
3. Security → App-Specific Passwords
4. Generate password
## Configuration File Structure
```json
{
"provider": "gmail",
"email": "user@gmail.com",
"password": "app-specific-password",
"from_name": "Display Name",
"from_email": "sender@example.com",
"profile_image": "/absolute/path/to/image.jpg",
"signature": "/absolute/path/to/signature.html",
"signatures": [
{"name": "work", "path": "/path/to/work.html"},
{"name": "personal", "path": "/path/to/personal.html"}
],
"default_ai_cli": "claude-code",
"license_key": "optional-license"
}
```
### Profile Image Configuration
The `profile_image` field allows you to include a profile picture in your emails:
* **Supported Formats**: PNG, JPG/JPEG, GIF, WebP
* **Path Type**: Absolute path to the image file
* **Email Embedding**: Image is embedded as base64 in HTML emails
* **Template Support**: Use `{{PROFILE_IMAGE}}` placeholder in custom templates
* **Display**: Appears as a circular profile photo (150px max width)
Example usage:
```bash
# During setup
mailos configure
# When prompted, enter: /Users/john/Pictures/profile.jpg
# Or directly via command line
mailos configure --image /Users/john/Pictures/profile.jpg
# For project-specific profile image
mailos configure --local --image ./assets/team-logo.png
```
### Email Signature Configuration
The `signature` field sets a default HTML signature file for your emails. For multiple signatures, use the `signatures` array:
* **Format**: Path to an HTML file containing your email signature
* **Usage**: Used by `mailos send` when no signature is specified inline
* **Integration**: Works with `applescripts/copy-email-signature.sh` to copy signatures to clipboard
* **Path Types**: Absolute or relative paths (relative to config location)
#### Single Signature
```bash
# Set a single global signature
mailos configure --signature /Users/john/signatures/work.html
# Or set via environment file
echo "MAILOS_SIGNATURE=/path/to/signature.html" >> ~/.email/.env
```
#### Multiple Signatures
Configure multiple signatures in your `config.json`:
```json
{
"signatures": [
{"name": "work", "path": "/Users/john/signatures/work.html"},
{"name": "personal", "path": "/Users/john/signatures/personal.html"},
{"name": "minimal", "path": "./signatures/minimal.html"}
]
}
```
Each signature needs:
* `name`: A short identifier used to select the signature
* `path`: Path to the HTML signature file (absolute or relative to config location)
**Using the AppleScript with multiple signatures:**
```bash
# List available signatures
applescripts/copy-email-signature.sh
# Output: Available signatures:
# - work -> /Users/john/signatures/work.html
# - personal -> /Users/john/signatures/personal.html
# Copy a specific signature by name
applescripts/copy-email-signature.sh work
# Output: Copied email signature to clipboard from /Users/john/signatures/work.html
```
**Raycast Integration:**
The script is configured as a Raycast script command with a dynamic dropdown. When you open Raycast and type the command:
1. The dropdown automatically populates with your configured signature names
2. Select a signature from the dropdown (e.g., "work", "personal")
3. The signature is copied to your clipboard as RTF
If only one signature is configured, it copies automatically without showing the dropdown.
To reload the dropdown options after changing your config, refresh the Raycast script commands (Cmd+R in Raycast preferences > Extensions).
## Security Best Practices
1. **Never commit credentials**: Local configs are auto-added to `.gitignore`
2. **Use app passwords**: Never use your main account password
3. **File permissions**: Config files are created with 600 permissions
4. **Encrypted storage**: Consider using encrypted filesystems
5. **Regular rotation**: Update app passwords periodically
## Multiple Accounts
To manage multiple email accounts:
1. **Global Default**: Set primary account globally
```bash
mailos configure --email primary@example.com
```
2. **Project Override**: Use different account per project
```bash
cd project1
mailos configure --local --email project1@example.com
cd ../project2
mailos configure --local --email project2@example.com
```
3. **Adding Aliases/Sub-emails**: Add additional email addresses from the same provider
```bash
mailos accounts --set alias@example.com
# Use the same credentials as your main account from that provider
```
For detailed account and alias management, see `mailos help accounts`.
## Troubleshooting
### Authentication Failed
* Verify app password is correct
* Check 2FA is enabled
* Ensure IMAP/SMTP access is enabled
* Try regenerating app password
### Local Config Not Working
* Ensure you're in the correct directory
* Check `.email/config.json` exists
* Verify JSON syntax is valid
* Check file permissions (should be 600)
### Provider Not Working
* Verify IMAP/SMTP settings are correct
* Check firewall/antivirus settings
* Some providers need "less secure apps" enabled
* Corporate accounts may have restrictions
### Inheritance Issues
* Local config only overrides specified fields
* Password cannot be inherited for security
* Run `mailos info` to see active configuration
## Advanced Configuration
### Custom Email Templates with Profile Images
When using custom email templates (via `mailos template`), you can include your profile image:
```html
{{PROFILE_IMAGE}}
{{FROM_NAME}}
{{BODY}}
```
The `{{PROFILE_IMAGE}}` placeholder will be replaced with your profile image embedded as base64 data.
### Custom SMTP/IMAP Settings
For providers not listed, use custom configuration:
```bash
mailos configure --provider custom
# You'll be prompted for:
# - SMTP Host
# - SMTP Port
# - IMAP Host
# - IMAP Port
# - TLS/SSL settings
```
### Environment Variables
Use `mailos env` to inspect and manage MailOS environment variables and project send defaults:
```bash
mailos env
mailos env --export
mailos whoami
```
Common send-related variables:
* `MAILOS_EMAIL_ADDRESS`: default account/credentials email for send flows
* `MAILOS_FROM_EMAIL`: outgoing `From` address; overrides `--account`
* `MAILOS_FROM_NAME`: outgoing display name
* `MAILOS_SIGNATURE`: default signature content, file path, or URL
* `MAILOS_PICTURE`: profile picture path
* `MAILOS_MEDIA`: path-list of default media attachments
MailOS resolves send defaults from exported environment variables, `./.env.mailos`, `./.env`, the nearest parent `emailos.json` or `emailos.toml`, and `~/.email/.env`. Most values only fill unset variables; `from_address` in project config deliberately controls `MAILOS_FROM_EMAIL` for that project.
For AI clients and wrapper shells that need resolved project values as real environment variables, run:
```bash
eval "$(mailos env --export)"
```
### Validation
Configuration is validated for:
* Valid email format
* Known provider settings
* Required fields present
* Password strength (warning only)
## See Also
* `mailos setup` - Initial setup wizard
* `mailos info` - Display current configuration
* `mailos local` - Create local configuration
* `mailos provider` - Configure AI provider
---
---
url: /file-config.md
---
# EmailOS File Config
EmailOS can read send-related defaults from repo-local JSON, TOML, and env files.
This is intended for values that are safe to commit, such as:
* default sender address
* default sender display name
* default signature source
Keep secrets such as passwords and tokens in env files or global config, not in `emailos.json` or `emailos.toml`.
## Repo-Local Project Config
EmailOS reads the nearest parent `emailos.json` or `emailos.toml` during `mailos send`, starting in the current directory and walking upward. If both files exist in the same directory, `emailos.json` wins.
Supported fields:
```json
{
"email_address": "user@website.com",
"from_address": "user@website.com",
"from_name": "My Name",
"signature": "https://example.com/email-signature.html",
"picture": "/path/to/profile-image.png",
"media": [
"assets/photo.png",
"/path/to/document.pdf"
],
"local_storage": false
}
```
The same values can be written as `emailos.toml`:
```toml
email_address = "user@website.com"
from_address = "user@website.com"
from_name = "My Name"
signature = "https://example.com/email-signature.html"
picture = "/path/to/profile-image.png"
media = [
"assets/photo.png",
"/path/to/document.pdf",
]
local_storage = false
```
Field mapping:
* `email_address` -> `MAILOS_EMAIL_ADDRESS`
* `from_address` -> `MAILOS_FROM_EMAIL`
* `from_name` -> `MAILOS_FROM_NAME`
* `signature` -> `MAILOS_SIGNATURE`
* `picture` -> `MAILOS_PICTURE`
* `media` -> `MAILOS_MEDIA`
* `local_storage` -> folder-specific `.email/` storage when set to `true`
Notes:
* `signature` may be inline text, a local file path, or an `http`/`https` URL.
* `media` may be a string or an array of local file paths in `emailos.json`, or an array of local file paths in `emailos.toml`. Relative paths are resolved from the directory containing the project config file. Use the `mailos send --media` flag for one-off media attachments that should not be saved in project config.
* Local `.email/` storage is disabled by default, even if a `.email/` directory already exists. Set `local_storage = true` to store MailOS drafts/sent exports under `.email/` next to the project config. MailOS adds that folder to the repository's local `.git/info/exclude`, not `.gitignore`, so files stay searchable locally without appearing in Git status.
* If `email_address` is omitted, EmailOS falls back to `from_address` when populating `MAILOS_EMAIL_ADDRESS`.
* `from_address` in project config is authoritative for send commands and overrides any existing `MAILOS_FROM_EMAIL` value.
## Env Files
EmailOS also reads env-style config files for send defaults.
Supported locations:
* `./.env.mailos`
* `./.env`
* `~/.email/.env`
Example `./.env.mailos`:
```bash
MAILOS_EMAIL_ADDRESS=user@website.com
MAILOS_FROM_NAME="My Name"
MAILOS_SIGNATURE="https://example.com/email-signature.html"
MAILOS_MEDIA="/path/to/photo.png:/path/to/document.pdf"
```
## Resolution Order
For `mailos send`, values are resolved in this order:
1. Existing exported environment variables
2. `./.env.mailos`
3. `./.env`
4. nearest parent `emailos.json` or `emailos.toml` (`from_address` overrides `MAILOS_FROM_EMAIL`)
5. `~/.email/.env`
Most values only fill unset variables, so earlier sources win. `from_address` is the exception: project config deliberately controls the outgoing sender for that project.
## Send Defaults
`mailos send` uses the resolved values to determine defaults such as:
* sender account email
* From address
* From display name
* signature source
* profile image
* media attachments
If `MAILOS_EMAIL_ADDRESS` is available from env or project config, `mailos send` uses it before falling back to local `./.email/config.json` account selection.
When project config sets `from_address`, `mailos send --from ...` and `mailos send --account ...` cannot change the project send account or outgoing `From` address. The CLI warns and keeps the project sender policy; update the project config file to change the sender.
## Diagnostics and Shell Export
Use these commands from the same directory where you will send:
```bash
mailos whoami
mailos config --values
mailos env
```
`mailos whoami` and `mailos config --values` show the resolved send values and their source. `mailos env` includes the nearest parent project config path, the resolved `MAILOS_FROM_EMAIL`, and a reminder that `MAILOS_FROM_EMAIL` controls the outgoing `From` address while `--account` selects credentials.
Some AI clients and shells only inspect actual process environment variables with commands such as `printenv`. Parent project config values are resolved by MailOS at runtime, so those tools will not see them until you export them:
```bash
eval "$(mailos env --export)"
```
`mailos env --export` prints shell-safe exports for non-secret send values only:
```bash
export MAILOS_EMAIL_ADDRESS='user@website.com'
export MAILOS_FROM_EMAIL='user@website.com'
export MAILOS_FROM_NAME='My Name'
```
It does not export secrets such as `MAILOS_APP_PASSWORD`.
## Recommended Split
Use `emailos.json` or `emailos.toml` for commit-safe team defaults:
* `email_address`
* `from_address`
* `from_name`
* `signature`
Use env files for local or sensitive values:
* `MAILOS_APP_PASSWORD`
* `APP_PASSWORD`
* API keys
* machine-specific overrides
## Global Profiles
Reusable project defaults can be saved on the user's machine as TOML profiles in `~/.email/configs`.
Save the nearest project config globally:
```bash
mailos env --save-profile work
```
Apply that profile to any folder:
```bash
cd ~/work/client-folder
mailos env work
```
This writes `./emailos.toml` from `~/.email/configs/work.toml`. Use `mailos env list` to see saved profile names and sender values together.
Applied profiles are added to the current repository's local `.git/info/exclude` by default so generated per-folder config stays out of code changes. Use `mailos env work --no-exclude` to leave Git excludes unchanged.
## Example Setup
`emailos.json`:
```json
{
"email_address": "user@website.com",
"from_address": "user@website.com",
"from_name": "My Name",
"signature": "https://gist.githubusercontent.com/anduimagui/e3ca5801a9d8ea7f000afee609ceab50/raw/2e2ec763ae71015f3c8bc289dab269f5d306aaa8/email-signature.html",
"media": [
"assets/photo.png"
],
"local_storage": true
}
```
Or `emailos.toml`:
```toml
email_address = "user@website.com"
from_address = "user@website.com"
from_name = "My Name"
signature = "https://gist.githubusercontent.com/anduimagui/e3ca5801a9d8ea7f000afee609ceab50/raw/2e2ec763ae71015f3c8bc289dab269f5d306aaa8/email-signature.html"
media = [
"assets/photo.png",
]
local_storage = true
```
Optional local override in `./.env.mailos`:
```bash
MAILOS_FROM_NAME="My Name"
```
Dry-run verification:
```bash
mailos send --to user@website.com --subject "Config check" --body "Testing config loading" --dry-run
```
---
---
url: /env.md
---
# MailOS Env Command
The `mailos env` command shows and manages MailOS environment variables and project send defaults.
Use it when you need to verify what `mailos send` will see from the current directory, including values resolved from a parent `emailos.json` or `emailos.toml`.
To select a repository-specific global account config through direnv, export `MAILOS_CONFIG_PATH`:
```bash
# .envrc
export MAILOS_CONFIG_PATH="$PWD/.private/emailos-config.json"
```
`MAILOS_CONFIG_PATH` controls the account config normally loaded from `~/.email/config.json`. It is separate from `emailos.toml`, which stores commit-safe project send defaults such as `from_address`, `from_name`, and `signature`.
## Basic Usage
```bash
mailos env
```
To apply a saved global project profile to the current folder:
```bash
mailos env work
```
This copies `~/.email/configs/work.toml` to `./emailos.toml` and adds `emailos.toml` to the current repository's local `.git/info/exclude`.
The output includes:
* resolved non-secret MailOS send variables
* the nearest parent `emailos.json` or `emailos.toml` path when one is found
* the source of `MAILOS_FROM_EMAIL`
* a reminder that `MAILOS_FROM_EMAIL` controls the outgoing `From` address and `--account` selects credentials
## Project Config Profiles
Project config profiles are reusable TOML send defaults stored on the user's machine under `~/.email/configs`.
Save the nearest project config as a global profile:
```bash
mailos env --save-profile work
```
List saved profiles and their resolved sender values:
```bash
mailos env list
```
Apply a profile to the current folder:
```bash
mailos env work
```
Applying a profile writes `./emailos.toml`. By default MailOS adds `emailos.toml` to the current repository's local `.git/info/exclude`, so the generated folder-specific config does not show up in code review or `git status`. Pass `--no-exclude` when you intentionally want Git to see the file.
If `./emailos.json` exists, MailOS refuses to apply the profile because JSON takes precedence over TOML in the same folder.
## Flags
| Flag | Type | Description | Example |
|------|------|-------------|---------|
| `--set-email` | string | Set `MAILOS_EMAIL_ADDRESS` in local `./.env` | `mailos env --set-email user@example.com` |
| `--set-from-email` | string | Set `MAILOS_FROM_EMAIL` in local `./.env` | `mailos env --set-from-email sender@example.com` |
| `--set-signature` | string | Set `MAILOS_SIGNATURE` in local `./.env` | `mailos env --set-signature "Regards"` |
| `--set-password` | string | Set `MAILOS_APP_PASSWORD` in local `./.env` | `mailos env --set-password app-password` |
| `--set-license` | string | Set `MAILOS_LICENSE_KEY` in local `./.env` | `mailos env --set-license license-key` |
| `--set-picture` | string | Set `MAILOS_PICTURE` in local `./.env` | `mailos env --set-picture /path/to/me.jpg` |
| `--show-local` | bool | Show local `./.env` contents | `mailos env --show-local` |
| `--show-global` | bool | Show global `~/.email/.env` contents | `mailos env --show-global` |
| `--edit-local` | bool | Print commands for editing local `./.env` | `mailos env --edit-local` |
| `--edit-global` | bool | Print commands for editing global `~/.email/.env` | `mailos env --edit-global` |
| `--list` | bool | List resolved MailOS environment variables | `mailos env --list` |
| `--export` | bool | Print resolved non-secret send values as shell exports | `mailos env --export` |
| `--save-profile` | string | Save nearest project config as `~/.email/configs/.toml` | `mailos env --save-profile work` |
| `--list-profiles` | bool | List global project config profiles | `mailos env list` |
| `--no-exclude` | bool | Do not add generated `emailos.toml` to local `.git/info/exclude` | `mailos env work --no-exclude` |
## Resolution Sources
For send diagnostics, MailOS combines:
1. existing exported environment variables
2. local `./.env.mailos`
3. local `./.env`
4. nearest parent `emailos.json` or `emailos.toml`
5. global `~/.email/.env`
Most file-based values only fill unset variables, so already-exported values normally win. `from_address` in project config is the exception: it deliberately controls the outgoing sender for that project and becomes `MAILOS_FROM_EMAIL`.
## Export for AI Clients
Some AI clients, shell wrappers, and IDE integrations only inspect real environment variables with commands such as `printenv`. They will not see values that MailOS resolves from a parent project config unless you export them first.
From the project folder, run:
```bash
eval "$(mailos env --export)"
```
Then tools in that shell can see values such as:
```bash
printenv MAILOS_FROM_EMAIL
```
`mailos env --export` emits shell-safe exports for non-secret send values only:
```bash
export MAILOS_EMAIL_ADDRESS='user@example.com'
export MAILOS_FROM_EMAIL='sender@example.com'
export MAILOS_FROM_NAME='Sender Name'
```
It does not emit secrets such as `MAILOS_APP_PASSWORD`, `MAILOS_LICENSE_KEY`, or account-specific password variables.
## Related Commands
Use `mailos whoami` or `mailos config --values` for a compact source report:
```bash
mailos whoami
mailos config --values
```
Use `mailos send --dry-run --verbose` to verify the final `From`, signature, media, and recipients before sending.
---
---
url: /send.md
---
# EmailOS Send Command Documentation
The `mailos send` command sends emails with support for markdown formatting, attachments, and signatures.
## Basic Usage
```bash
mailos send --to recipient@example.com --subject "Subject" --body "Message"
```
If the nearest `emailos.json` or `emailos.toml` sets `from_address`, that project sender policy controls the send account and outgoing `From` address. Passing `--from` or `--account` selects an account only when no project sender policy is present; otherwise MailOS warns and keeps the project config values.
To send a quick test email to the resolved sender address, use [`mailos echo`](echo.md). It reuses the `mailos send` delivery path and fills `--to` from the current project or the default machine MailOS account.
## Project Media
`mailos send` can attach media files explicitly with `--media`, and it automatically attaches files listed in `emailos.json` or `emailos.toml` under `media`, in addition to any `--attach` files:
```bash
mailos send --to recipient@example.com --subject "Photos" --body "See attached" --media assets/photo.png
```
```json
{
"media": ["assets/photo.png", "/path/to/document.pdf"]
}
```
Relative media paths are resolved from the directory containing the project config file.
## Email Preheaders
The preheader is a brief text snippet that appears after the subject line in email clients' inbox view. It provides additional context to encourage recipients to open your email.
### Best Practices
* Keep it between 30-100 characters
* Don't duplicate the subject line
* Use it to add compelling details or create curiosity
* Include a call to action when appropriate
### Example
```bash
mailos send \
--to customer@example.com \
--subject "Your order has shipped!" \
--preheader "Track your package with the link inside" \
--body "Your order #12345 is on its way..."
```
## Command-Line Flags
### Basic Options
| Flag | Short | Type | Default | Description | Example |
|------|-------|------|---------|-------------|---------|
| `--account` | | string | | Email account to use | `mailos send --account value` |
| `--bcc` | | \[]string | | BCC recipients | `mailos send --bcc value` |
| `--body` | `-b` | string | | Email body (Markdown supported). Use @path/to/file to load file content | `mailos send --body value` |
| `--cc` | `-c` | \[]string | | CC recipients | `mailos send --cc value` |
| `--from` | | string | | Email account to use (alias for `--account`) | `mailos send --from value` |
| `--subject` | `-s` | string | | Email subject | `mailos send --subject value` |
| `--to` | `-t` | \[]string | | Recipient email addresses | `mailos send --to value` |
### Advanced Options
| Flag | Short | Type | Default | Description | Example |
|------|-------|------|---------|-------------|---------|
| `--attach` | `-a` | \[]string | | Attachments | `mailos send --attach value` |
| `--check-duplicate` | | bool | false | Check if email with same subject has already been sent to recipients | `mailos send --check-duplicate` |
| `--confirm` | | bool | false | Confirm before sending each draft | `mailos send --confirm` |
| `--delete-after` | | bool | true | Delete drafts after successful sending | `mailos send --delete-after` |
| `--draft-dir` | | string | | Directory containing draft emails (default: ~/.email/drafts) | `mailos send --draft-dir value` |
| `--drafts` | | bool | false | Send all draft emails from .email/drafts folder | `mailos send --drafts` |
| `--electron-path` | | string | | Custom path to Electron app (default: ~/Desktop/mailos-electron-ui) | `mailos send --electron-path value` |
| `--file` | `-f` | string | | Read body from file | `mailos send --file value` |
| `--filter` | | string | | Filter drafts (e.g., 'priority:high', 'to:\*@example.com') | `mailos send --filter value` |
| `--force` | | bool | false | Force send email bypassing dynamic content warnings and template validation | `mailos send --force` |
| `--forward-message-id` | | string | | Append the matching received email thread by Message-ID below the message body | `mailos send --forward-message-id value` |
| `--forward-message-link` | | string | | Append the matching received email thread from a mail client message link, such as macOS Mail `message://...` | `mailos send --forward-message-link value` |
| `--from-name` | | string | | Override the sender's display name | `mailos send --from-name value` |
| `--group` | `-g` | string | | Send to a saved email group or local recipient metadata file | `mailos send --group value` |
| `--input` | | bool | false | Open Electron UI for composing email instead of sending directly | `mailos send --input` |
| `--log-file` | | string | | Log sent emails to file | `mailos send --log-file value` |
| `--media` | | \[]string | | Media attachments such as photos, PDFs, or other files | `mailos send --media value` |
| `--model` | | string | | Model to use for natural language parsing (auto-detects if not specified) | `mailos send --model value` |
| `--no-popup` | | bool | true | Skip confirmation popup and send directly | `mailos send --no-popup` |
| `--no-signature` | | bool | false | No signature | `mailos send --no-signature` |
| `--no-validate` | | bool | false | Skip email address validation | `mailos send --no-validate` |
| `--ollama-url` | | string | http://localhost:11434 | Ollama server URL for natural language processing | `mailos send --ollama-url value` |
| `--plain` | `-p` | bool | false | Send as plain text | `mailos send --plain` |
| `--preheader` | | string | | Brief preview text shown after subject line (30-100 characters recommended) | `mailos send --preheader value` |
| `--provider` | | string | ollama | AI provider for natural language parsing (ollama|vllm) | `mailos send --provider value` |
| `--replace` | | \[]string | | Replace dynamic content with KEY=VALUE pairs (e.g., --replace USER\_NAME=John --replace DATE=2024-01-01) | `mailos send --replace value` |
| `--schedule-at` | | string | | Schedule email to be sent at specific time (RFC3339 format: 2024-01-01T15:04:05Z) | `mailos send --schedule-at value` |
| `--schedule-cancel` | | bool | false | Cancel scheduled emails (use with --filter) | `mailos send --schedule-cancel` |
| `--schedule-in` | | string | | Schedule email to be sent after duration (e.g., '1h30m', '2h', '30s') | `mailos send --schedule-in value` |
| `--schedule-list` | | bool | false | List all scheduled emails | `mailos send --schedule-list` |
| `--signature` | | string | | Custom signature | `mailos send --signature value` |
| `--template` | | bool | false | Apply HTML template to email | `mailos send --template` |
| `--template-html` | | string | | Path to custom HTML template file | `mailos send --template-html value` |
| `--validate` | | bool | true | Validate recipient email addresses before sending (enabled by default) | `mailos send --validate` |
| `--validate-smtp` | | bool | false | Perform SMTP verification during validation (slower but more thorough) | `mailos send --validate-smtp` |
| `--vllm-url` | | string | http://localhost:8290 | VLLM server URL for natural language processing | `mailos send --vllm-url value` |
### Output Options
| Flag | Short | Type | Default | Description | Example |
|------|-------|------|---------|-------------|---------|
| `--dry-run` | | bool | false | Preview what would be sent without actually sending | `mailos send --dry-run` |
| `--preview` | | bool | false | Preview the complete email without sending | `mailos send --preview` |
| `--verbose` | `-v` | bool | false | Show detailed SMTP debugging information | `mailos send --verbose` |
## Email Address Validation
EmailOS automatically validates recipient email addresses before sending to prevent bounce-backs. Validation is **enabled by default** and checks:
1. **Email syntax** - Verifies the email format is valid
2. **Domain existence** - Confirms the domain exists via DNS lookup
3. **MX records** - Checks if the domain can receive email
### Validation Behavior
```bash
# Default behavior - validation is automatic
mailos send --to user@example.com --subject "Test" --body "Hello"
# If validation fails, you'll see an error:
# Error: Email validation failed for the following recipients:
# - invalid@nonexistent-domain.xyz
# Error: Domain does not exist
# Details: The domain 'nonexistent-domain.xyz' could not be found.
```
### Bypassing Validation
```bash
# Skip validation entirely
mailos send --to user@example.com --subject "Test" --body "Hello" --no-validate
# Force send even if validation fails (shows warning)
mailos send --to user@example.com --subject "Test" --body "Hello" --force
```
### Verbose Validation
```bash
# See detailed validation output
mailos send --to user@example.com --subject "Test" --body "Hello" --verbose
# Output: Validating recipient email addresses...
# Output: All recipient email addresses validated successfully
```
### Standalone Validation
For bulk validation before sending, use the dedicated `validate` command:
```bash
# Validate addresses without sending
mailos validate user1@gmail.com user2@outlook.com --verbose
# See validate command documentation for more options
mailos validate --help
```
## Markdown Support
By default, markdown in the message body is converted to HTML:
### Supported Markdown
* **Bold**: `**text**` or `__text__`
* *Italic*: `*text*` or `_text_`
* `Code`: `` `code` ``
* Links: `[text](url)`
* Lists: `- item` or `1. item`
* Headers: `# Header`
* Code blocks: ` `language \`\`\`
### Example with Markdown
```bash
mailos send \
--to team@example.com \
--subject "Project Update" \
--body "## Status Update
**Completed:**
- Feature A
- Feature B
*In Progress:*
- Feature C
See [documentation](https://example.com)"
```
## Input Methods
### 1. Command Line
```bash
mailos send --to user@example.com --subject "Test" --body "Message"
```
### 2. From File
```bash
mailos send --to user@example.com --subject "Report" --file ./report.md
```
### 3. Recipient Group From Markdown or Text
`--group` can be either a saved MailOS group name or a local `.md`,
`.markdown`, or `.txt` file with recipient metadata. Use this for reusable
recipient sets with `to`, `cc`, and `bcc`; the email body still comes from
`--body`, stdin, or `--file`.
```bash
mailos send --group ./recipients.md --body "Hello team"
mailos send --group ./recipients.txt --body "Hello team" --plain
```
Frontmatter format:
```markdown
---
name: "Andrew Maguire"
to:
- alpha@example.com
- beta@example.com
cc: ops@example.com
bcc:
- archive@example.com
subject: "Project update"
description: "Short inbox preview"
signature: "Regards, Andrew"
file:
- /path/to/report.pdf
---
Optional notes about this recipient set.
```
Plain metadata format without frontmatter delimiters:
```text
to: alpha@example.com, beta@example.com
cc: ops@example.com
bcc: archive@example.com
name: Andrew Maguire
signature: "Regards, Andrew"
```
Supported metadata keys are `to`, `cc`, `bcc`, `subject`, `name`, `from_name`,
`description`, `preheader`, `signature`, `group`, `priority`, and `file`.
`description` is used as the preheader when `preheader` is not set. When
`--group` points to a file, at least one `to`, `cc`, or `bcc` recipient must be
present.
### 4. Body From File Path (`--body`)
```bash
mailos send --to user@example.com --subject "Weekly Update" --body @./examples/send-bodies/plain-update.txt
```
Use `@@` to send a literal value that starts with `@`:
```bash
mailos send --to user@example.com --subject "Literal" --body "@@start-with-at"
```
### 5. Interactive (stdin)
```bash
mailos send --to user@example.com --subject "Notes"
# Then type your message and press Ctrl+D
```
### 6. Piped Input
```bash
echo "Automated message" | mailos send --to admin@example.com --subject "Alert"
```
### 7. Include a Previous Chain as Forwarded Text
```bash
mailos send --to colleague@example.com --subject "FYI" --body "Adding this for context." --forward-message-id ""
```
When copying a macOS Mail deeplink, use `--forward-message-link` for clarity:
```bash
mailos send --to colleague@example.com --subject "FYI" --body "Adding this for context." --forward-message-link "message://%3cabc123%40example.com%3e"
```
## Signature Management
### Default Signature
Automatically appends:
```
--
Your Name
your.email@example.com
```
### Custom Signature
```bash
mailos send \
--to client@example.com \
--subject "Proposal" \
--body "Please find attached..." \
--signature "Best regards,\nJohn Smith\nSales Manager\nCompany Inc."
```
### No Signature
```bash
mailos send --to user@example.com --subject "Test" --body "Message" --no-signature
```
## Account Selection
Use `--account` to choose the authenticated mailbox for SMTP credentials. `--from` is an alias of `--account`.
If the nearest parent `emailos.json` or `emailos.toml` sets `from_address`, that project sender policy wins. Passing `--from` or `--account` will not change the project send account or outgoing `From` address; MailOS warns and continues to use project config. Change `email_address` or `from_address` in the project config when the project sender should change.
### Usage
```bash
# Send using a specific authenticated account
mailos send --to recipient@example.com --subject "Test" --body "Hello" --account work@company.com
# Equivalent alias
mailos send --to recipient@example.com --subject "Test" --body "Hello" --from work@company.com
```
### Account Management
* Use `mailos accounts` to list configured accounts and aliases
* Use `mailos account --set [EMAIL]` to set the default account for the session
* Use `mailos account --clear` to clear the session default account
* If `--account`/`--from` is not specified, the configured default account is used
* The account must be properly authenticated with valid credentials
## Sender Policy (`MAILOS_FROM_EMAIL`)
Set `MAILOS_FROM_EMAIL` in your environment to enforce the outgoing `From` address used for sending.
```bash
export MAILOS_FROM_EMAIL="andrew@happysoft.dev"
mailos send --account andrewmou@fastmail.com --to andremg212@gmail.com --subject "Test" --body "Hello"
```
Behavior when `MAILOS_FROM_EMAIL` is set:
* Email sending is allowed (not blocked)
* The message is sent using `MAILOS_FROM_EMAIL` as the `From` address
* If `--account` differs, EmailOS logs that it will still send using `MAILOS_FROM_EMAIL`
* End-of-send output includes a policy reminder that emails are sent with `MAILOS_FROM_EMAIL`
Use only `MAILOS_FROM_EMAIL` for sender policy configuration.
### Project Config and AI Shells
`MAILOS_FROM_EMAIL` may come from the real process environment, a local env file, or the nearest parent project config `from_address`. A plain `printenv MAILOS_FROM_EMAIL` only shows real environment variables, so it can miss values that MailOS resolves from `emailos.json` or `emailos.toml`.
Check MailOS' resolved send values with:
```bash
mailos config --values
mailos env
```
If an AI client or wrapper script needs the resolved values as real shell variables, run:
```bash
eval "$(mailos env --export)"
```
`mailos env --export` exports non-secret send values such as `MAILOS_EMAIL_ADDRESS`, `MAILOS_FROM_EMAIL`, `MAILOS_FROM_NAME`, `MAILOS_SIGNATURE`, `MAILOS_PICTURE`, and `MAILOS_MEDIA`.
## Multiple Recipients
### Using Comma Separation
```bash
mailos send \
--to "user1@example.com,user2@example.com,[USER3_ADDRESS]" \
--cc "manager@example.com" \
--bcc "archive@example.com" \
--subject "Team Update" \
--body "Meeting at 3pm"
```
### Using Multiple Flags
```bash
mailos send \
--to user1@example.com \
--to user2@example.com \
--cc manager@example.com \
--subject "Notice" \
--body "Important information"
```
## Attachments
### Single Attachment
```bash
mailos send \
--to recipient@example.com \
--subject "Report" \
--body "Please see attached" \
--attach report.pdf
```
### Media Attachment
```bash
mailos send \
--to recipient@example.com \
--subject "Photo" \
--body "Please see attached media" \
--media assets/photo.png
```
### Multiple Attachments
```bash
mailos send \
--to team@example.com \
--subject "Documents" \
--body "All requested files attached" \
--attach "file1.pdf,file2.docx,data.xlsx"
```
## Email Scheduling
You can schedule emails to be sent at a specific time or after a delay using the scheduling flags.
### Schedule for Specific Time
```bash
mailos send \
--to recipient@example.com \
--subject "Meeting Reminder" \
--body "Don't forget our meeting tomorrow" \
--schedule-at "2024-01-15T09:00:00Z"
```
### Schedule with Delay
```bash
mailos send \
--to team@example.com \
--subject "Weekly Update" \
--body "Here's this week's progress..." \
--schedule-in "2h30m"
```
### Scheduling Flags
| Flag | Description | Example |
|------|-------------|---------|
| `--schedule-at` | Schedule for specific time (RFC3339 format) | `--schedule-at "2024-01-15T09:00:00Z"` |
| `--schedule-in` | Schedule after duration | `--schedule-in "1h30m"` |
| `--schedule-list` | List all scheduled emails | `--schedule-list` |
| `--schedule-cancel` | Cancel scheduled emails | `--schedule-cancel --filter "to:*@example.com"` |
## Sending Draft Emails
You can send all emails from your drafts folder at once using the `--drafts` flag.
### Basic Draft Sending
```bash
mailos send --drafts
```
### Draft Sending with Options
```bash
mailos send --drafts \
--dry-run \
--confirm \
--filter "priority:high" \
--log-file sent_drafts.log
```
### Draft Flags
| Flag | Description | Default | Example |
|------|-------------|---------|---------|
| `--drafts` | Send all draft emails | false | `--drafts` |
| `--draft-dir` | Directory containing drafts | ~/.email/drafts | `--draft-dir ./my-drafts` |
| `--confirm` | Confirm before sending each draft | false | `--confirm` |
| `--delete-after` | Delete drafts after sending | true | `--delete-after` |
| `--filter` | Filter which drafts to send | | `--filter "to:*@company.com"` |
| `--log-file` | Log sent emails to file | | `--log-file sent.log` |
## HTML Templates
If you have configured an HTML template using `mailos template`, it will automatically be applied to your emails unless you use `--plain`.
### Custom HTML Template Files
Use the `--template-html` flag to specify a custom HTML template file for dynamic templating:
```bash
mailos send \
--to recipient@example.com \
--subject "Professional Email" \
--preheader "Custom template with responsive design" \
--body "## Welcome to Our Service
Thank you for your interest in our product.
### Key Benefits:
- Professional email design
- Responsive layout
- Custom branding
- Markdown content support
Best regards!" \
--template-html ./custom-template.html
```
#### Template Processing Logic
The system intelligently inserts your content using multiple strategies:
1. **{{BODY}} Placeholder**: If your template contains `{{BODY}}`, content is inserted there
2. **Content Recognition**: Automatically replaces sample content in common templates
3. **Smart Insertion**: Finds `` or `` tags for content placement
4. **Preheader Replacement**: Automatically updates preheader text in templates
#### Supported Template Features
* **Markdown Conversion**: Your Markdown content is converted to HTML before insertion
* **Preheader Integration**: Custom preheader text replaces template placeholder
* **Responsive Design**: Works with any responsive email template
* **Professional Styling**: Maintains template styling while inserting your content
#### Template Examples
```bash
# Use a downloaded template
mailos send --template-html ./responsive-email.html --body "Your content here"
# With preheader customization
mailos send --template-html ./template.html --preheader "Preview text" --body "Email body"
# Combine with other features
mailos send --template-html ./branded.html --attach file.pdf --body "**Markdown** content"
```
## Examples
### Simple Text Email
```bash
mailos send \
--to friend@example.com \
--subject "Hello" \
--body "How are you?" \
--plain
```
### Professional Email with Markdown
```bash
mailos send \
--to client@company.com \
--subject "Project Proposal" \
--preheader "Comprehensive solution for your digital transformation needs" \
--body "Dear Client,
**Project Overview**
We are pleased to present our proposal for your consideration.
## Deliverables
1. Design phase
2. Implementation
3. Testing
4. Deployment
Please review and let us know if you have questions.
Best regards"
```
### Email from Template File
```bash
# Create template file
cat > email_template.md << EOF
Dear {{Name}},
Thank you for your interest in our services.
**Next Steps:**
- Schedule a call
- Review documentation
- Sign agreement
Best regards,
Sales Team
EOF
# Send using template
mailos send \
--to [PROSPECT_ADDRESS] \
--subject "Follow-up" \
--file email_template.md
```
### Batch Email Script
```bash
#!/bin/bash
for email in $(cat recipients.txt); do
mailos send \
--to "$email" \
--subject "Newsletter" \
--file newsletter.md \
--attach newsletter.pdf
done
```
## Confirmation Popup System
EmailOS includes a built-in confirmation popup system to ensure safety when sending emails on your behalf, especially when using AI features.
### Default Behavior
When sending emails, a native system dialog appears showing:
* **Email details**: Recipients, subject, and body preview
* **⏰ 5-second countdown**: Email will be sent automatically after 5 seconds
* **🔑 Keyboard shortcuts**: ENTER to send immediately, ESC to cancel
* **Manual controls**: "Cancel" and "Send Now" buttons
### User Options
1. **Auto-send**: Wait 5 seconds for automatic sending (default behavior)
2. **Quick send**: Press ENTER to send immediately
3. **Cancel**: Press ESC or click "Cancel" to abort sending
4. **Manual choice**: Click "Send Now" or "Cancel" buttons
### Bypassing the Popup
For automated scripts or when you want to skip confirmation:
```bash
mailos send --to user@example.com --subject "Test" --body "Message" --no-popup
```
### Platform Support
* **macOS**: Native AppleScript dialogs with system styling
* **Linux**: zenity or kdialog integration
* **Windows**: PowerShell-based dialogs
* **Fallback**: Cross-platform dialog library
### When Popup is Skipped
The confirmation popup is automatically bypassed for:
* `--dry-run` mode (preview only)
* `--no-popup` flag usage
* Scheduled emails (`--schedule-at` / `--schedule-in`)
* Draft batch sending (`--drafts` uses its own confirmation system)
### Examples
```bash
# Default behavior - shows 5-second countdown popup
mailos send --to user@example.com --subject "Test" --body "Hello"
# Skip popup for automated sending
mailos send --to user@example.com --subject "Auto" --body "Automated message" --no-popup
# Preview without popup or sending
mailos send --to user@example.com --subject "Preview" --body "Test" --dry-run
```
## Error Handling
Common errors and solutions:
### Authentication Failed
* Verify email credentials: `mailos info`
* Check app-specific password for Gmail/Outlook
* Ensure 2FA is properly configured
### Attachment Not Found
* Use absolute paths for attachments and media when needed
* Check file permissions
* Verify file exists before sending
### SMTP Connection Failed
* Check internet connection
* Verify SMTP settings for your provider
* Ensure firewall allows SMTP ports
### Popup Dialog Issues
* **Dialog not appearing**: Check system permissions for AppleScript (macOS) or GUI access
* **Dialog cancelled error**: This is normal when user presses ESC or cancels
* **Fallback to terminal**: If GUI dialogs fail, EmailOS will prompt in the terminal
## Notes
* Email body supports UTF-8 encoding
* Use `--media` for photos, PDFs, and other media-style files that should be attached to a send.
* Maximum attachment size depends on provider (usually 25MB)
* HTML and plain text versions are sent as multipart/alternative
* Sent emails are saved to Sent folder when IMAP is configured
* Use `--plain` to force plain text only
* Markdown tables are supported in HTML output
---
---
url: /read.md
---
# EmailOS Read Command Documentation
The `mailos read` command displays the full content of a specific email by its ID or from email files.
For Apple Mail URL handling and macOS-specific attachment export behavior, see [macOS Mail Integration](clients/macos-mail.md).
## Basic Usage
```bash
# Read from IMAP by email ID
mailos read [email_id]
# Read from email file
mailos read --file [email_file]
```
Displays the complete content of the specified email, including body text and attachment information. Supports reading from IMAP accounts or directly from email files in multiple formats (.eml, .mbox, .emlx, .msg).
## Command-Line Flags
### Basic Options
| Flag | Short | Type | Default | Description | Example |
|------|-------|------|---------|-------------|---------|
| `--account` | | string | | Email account to use | `mailos read --account value` |
| `--from` | | string | | Filter emails by sender (e.g., --from user@domain.com) | `mailos read --from value` |
| `--limit` | | int | 10 | Limit number of recent emails to read | `mailos read --limit value` |
### Advanced Options
| Flag | Short | Type | Default | Description | Example |
|------|-------|------|---------|-------------|---------|
| `--copy` | | bool | false | Copy email to clipboard after reading | `mailos read --copy` |
| `--attachment-timeout` | | int | 30 | Timeout in seconds for attachment export fallback via Mail.app (macOS) | `mailos read --attachment-timeout 15` |
| `--content` | | string | | Read from raw text content instead of IMAP lookup | `mailos read --content "From: a@example.com\nSubject: Hi\n\nBody"` |
| `--content-file` | | string | | Read raw text content from a file path | `mailos read --content-file /tmp/mail.txt` |
| `--content-from` | | string | | Optional sender used when reading from content input | `mailos read --content "Body" --content-from sender@example.com` |
| `--content-html` | | string | | Optional HTML body to use for markdown/link extraction with content input | `mailos read --content "Body" --content-html "
Body
"` |
| `--content-stdin` | | bool | false | Read raw text content from stdin | `pbpaste | mailos read --content-stdin` |
| `--content-subject` | | string | | Optional subject used when reading from content input | `mailos read --content "Body" --content-subject "Clipboard Email"` |
| `--eml-file` | | string | | Read email from file (.eml, .mbox, .emlx, .msg) | `mailos read --eml-file value` |
| `--eml-output` | | string | | Directory to save EML file (default: current directory) | `mailos read --eml-output value` |
| `--export-eml` | | bool | false | Export email to EML format | `mailos read --export-eml` |
| `--file` | | string | | Alias for --eml-file (read from email file) | `mailos read --file value` |
| `--last` | | int | 0 | Show last N emails (alternative to --limit) | `mailos read --last value` |
| `--list` | | bool | false | List recent emails with IDs for selection | `mailos read --list` |
| `--links-only` | | bool | false | Output only extracted links for the target email | `mailos read --links-only` |
| `--links-resolve-tracking` | | bool | false | Resolve tracking/redirect URLs to final destinations when possible | `mailos read --links-resolve-tracking` |
| `--max-links` | | int | 0 | Maximum number of extracted links to output (0 = no limit) | `mailos read --max-links 10` |
| `--markdown` | | bool | true | Output email as plain markdown (default true) | `mailos read --markdown` |
| `--message-id` | | string | | Message-ID to read (auto sync+retry on miss) | `mailos read --message-id value` |
| `--message-link` | | bool | false | Print macOS message: URI for the resolved email | `mailos read --message-link` |
| `--open-eml` | | bool | false | Export email to EML format and open in default mail client | `mailos read --open-eml` |
| `--open-message-link` | | bool | false | Open macOS message: URI for the resolved email | `mailos read --open-message-link` |
| `--recent` | | bool | false | Show recent emails without requiring Message-ID | `mailos read --recent` |
| `--save-attachments` | | string | | Directory to save attachments to disk (macOS can export via Mail.app by Message-ID) | `mailos read --save-attachments value` |
| `--show-attachments` | | bool | true | Display attachment previews when available | `mailos read --show-attachments` |
| `--suppress-attachment-errors` | | bool | false | Do not include attachment export errors in markdown output | `mailos read --suppress-attachment-errors` |
| `--sync` | | bool | false | Fetch latest emails and retry Message-ID lookup when not found (for positional IDs) | `mailos read --sync` |
| `--temp-eml` | | bool | false | Create temporary EML file (deleted after 5 minutes) | `mailos read --temp-eml` |
| `--thread-id` | | string | | Thread-ID to read | `mailos read --thread-id value` |
| `--uid` | | uint32 | 0 | Email UID from search results (stable handoff for mailos read) | `mailos read --uid value` |
| `--write-md` | | string | | Write full email content to markdown file (specify filename or directory) | `mailos read --write-md value` |
### Output Options
| Flag | Short | Type | Default | Description | Example |
|------|-------|------|---------|-------------|---------|
| `--include-documents` | | bool | true | Parse and display attachment document content inline | `mailos read --include-documents` |
| `--include-links` | | bool | false | Include URLs and Links section in read output | `mailos read --include-links` |
| `--json` | | bool | false | Output emails in JSON format | `mailos read --json` |
`--json` with a specific email target now includes a standardized `links` array with per-link metadata (`text`, `url`, `canonical_url`, `resolved_url`, `type`, `source`).
Markdown output now linkifies detected URLs and bare domains (for example `meet.google.com/...`) into Markdown links, and appends a standardized `Links:` section.
## Getting Email IDs
Before using the read command, you need to find the email ID using the search command:
```bash
# Search for emails to get IDs
mailos search
mailos search --from john@example.com
mailos search --subject "meeting"
```
The search results will show email IDs that you can then use with the read command.
## Reading from Email Files
The `mailos read` command can read emails directly from files without requiring an IMAP connection. This is useful for:
* Viewing archived emails (.eml files)
* Reading emails exported from other clients
* Processing batch email files
* Working offline with email data
### Supported Formats
| Format | Extension | Description | Status |
|--------|-----------|-------------|--------|
| **EML** | `.eml` | Standard MIME email format | ✅ Full support |
| **MBOX** | `.mbox` | Unix mailbox format (extracts first message) | ✅ Supported |
| **EMLX** | `.emlx` | Apple Mail format | ✅ Supported |
| **MSG** | `.msg` | Outlook message format | ⚠️ Limited (shows conversion instructions) |
### File Reading Examples
```bash
# Read standard EML file
mailos read --file email.eml
# Read Unix mailbox file
mailos read --file archive.mbox
# Read Apple Mail file
mailos read --file message.emlx
# Read and export to markdown
mailos read --file email.eml --write-md output.md
# Read with attachment extraction
mailos read --file email.eml --save-attachments ./attachments/
# Read Outlook MSG file (shows conversion instructions)
mailos read --file outlook.msg
```
### Format-Specific Notes
**MBOX Files:**
* If the mbox file contains multiple messages, only the first message is displayed
* Additional messages are ignored with a warning message
**EMLX Files (Apple Mail):**
* XML metadata (plist) is automatically stripped from output
* Byte-count header is properly handled
**MSG Files (Outlook):**
* Currently not fully supported
* Command shows helpful error with conversion tool suggestions (msgconvert, outlook-msg-reader)
* Convert to .eml format first for best compatibility
## Examples
### Read a specific email by ID
```bash
mailos read 1423
```
### Read email using the --uid flag
```bash
mailos read --uid 1423
```
### Read raw content without IMAP
```bash
mailos read --content-file /tmp/mail.txt --include-links
pbpaste | mailos read --content-stdin --content-subject "Clipboard Email"
```
### Read by Message-ID URI directly
```bash
mailos read "message://%3c79943605-7e8a-4e8a-970d-c2adec786dc1%40mtasv.net%3e"
```
### Print email as markdown directly
```bash
mailos read --message-id "<79943605-7e8a-4e8a-970d-c2adec786dc1@mtasv.net>" --account andrew@email-os.com --markdown
```
### Read email without parsing document attachments
```bash
mailos read 1423 --include-documents=false
```
### Read from EML file
```bash
mailos read --file email.eml
```
### Read from mbox file and export to markdown
```bash
mailos read --file archive.mbox --write-md conversation.md
```
### Read from Apple Mail file
```bash
mailos read --file message.emlx
```
### Read email file with attachment extraction
```bash
mailos read --file email.eml --save-attachments ./attachments/
```
## Output Format
The read command displays:
* **Email Headers**: From, To, Subject, Date, Message-ID
* **Email Body**: Full text content (HTML is converted to plain text)
* **Attachments**: List of attachment filenames
* **Document Content**: If `--include-documents` is enabled, displays parsed content from document attachments
## Integration with Search and Files
### IMAP Workflow
Typical workflow for reading from your email account:
```bash
# 1. Search for emails to find IDs
mailos search --from important@client.com
# 2. Read specific email from search results
mailos read 1423
# 3. Use search filters to narrow down results
mailos search --subject "contract" --has-attachments
mailos read 1445
```
### File-Based Workflow
Working with email files directly:
```bash
# Read standalone email files
mailos read --file backup/important-email.eml
# Process multiple formats
mailos read --file exports/gmail-archive.mbox
mailos read --file apple-mail/message.emlx
# Export file content to markdown
mailos read --file email.eml --write-md analysis.md
```
## Error Handling
Common errors and solutions:
```bash
# Invalid email ID format
Error: Email ID 'abc' is not a valid number
# Solution: Use numeric email IDs only
# Missing email ID
Error: Please provide an email ID
# Solution: Run 'mailos search' first to get email IDs
# Email not found
Error: Email with ID 9999 not found
# Solution: Verify the email ID exists using 'mailos search'
```
## Notes
* Email IDs are obtained from the `mailos search` command
* The command reads from your configured email account or from email files
* Supports multiple email file formats: .eml, .mbox, .emlx, .msg (limited)
* Document parsing supports common formats (PDF, DOC, etc.)
* Large emails may take longer to load and display
* Email content is displayed in plain text format
* File reading works offline without IMAP connection
* MBOX files: only first message is read from multi-message files
## Troubleshooting
### Email not found
1. Verify the email ID is correct from search results
2. Check if email has been deleted or moved
3. Ensure you have access to the email account
### Authentication errors
1. Check your email configuration: `mailos setup`
2. Verify your email password/app password is correct
3. Ensure IMAP access is enabled for your email provider
### Document parsing issues
1. Use `--include-documents=false` to skip document parsing
2. Check if the attachment format is supported
3. Verify attachment isn't corrupted
## See Also
* [`mailos search`](search.md) - Find emails and get IDs for reading
* [`mailos reply`](reply.md) - Reply to emails after reading them
---
---
url: /search.md
---
# EmailOS Search Command Documentation
The `mailos search` command provides advanced email search capabilities with fuzzy matching, boolean operators, flexible date ranges, and size filters.
## Basic Usage
```bash
mailos search
```
Searches and displays unlimited emails by default (use --limit to restrict). The search command uses cached emails from your local inbox for fast searching. Use sync options to update the cache with latest emails.
## Quick Examples
```bash
# Boolean search with OR operator
mailos search -q "urgent OR deadline OR important"
# Field-specific search
mailos search -q "from:support AND subject:invoice"
# Date range with size filter
mailos search --date-range "last week" --min-size 1MB
# Complex query with NOT operator
mailos search -q "project AND NOT spam" --has-attachments
# Fuzzy search for typos
mailos search --from "supprt" # matches "support"
# Resync emails before searching
mailos search --resync --from "important@client.com"
# Search with attachment filtering
mailos search --has-attachments --attachment-size 1MB
# Search sent emails with alias authentication
mailos search --type sent --account user@example.com -q "contract"
# Advanced domain filtering
mailos search --external-only --exclude-domains spam.com,ads.com
# Content and body analysis
mailos search --body-contains "confidential" --word-count 100 --html-only
# Threading and conversation analysis
mailos search --is-reply --conversation-length 3
# Security and verification filtering
mailos search --encrypted --dkim-status pass --importance high
```
## Command-Line Flags
### Basic Options
| Flag | Short | Type | Default | Description | Example |
|------|-------|------|---------|-------------|---------|
| `--body` | | string | | Search in email body content | `mailos search --body value` |
| `--days` | | int | 0 | search emails from last n days | `mailos search --days value` |
| `--from` | | string | | filter by sender | `mailos search --from value` |
| `--limit` | | int | 0 | number of emails to search (0 = no limit) - alias for --number | `mailos search --limit value` |
| `--number` | `-n` | int | 0 | number of emails to search (0 = no limit) | `mailos search --number value` |
| `--subject` | | string | | filter by subject | `mailos search --subject value` |
| `--to` | | string | | filter by recipient (defaults to from-email in config if set) | `mailos search --to value` |
| `--type` | | string | inbox | email type to search (inbox, sent, drafts, all) | `mailos search --type value` |
| `--unread` | `-u` | bool | false | show only unread emails | `mailos search --unread` |
### Advanced Options
| Flag | Short | Type | Default | Description | Example |
|------|-------|------|---------|-------------|---------|
| `--alltime` | | bool | false | Search all emails (overrides default 30-day limit) | `mailos search --alltime` |
| `--attachment-count` | | int | 0 | Filter by minimum number of attachments | `mailos search --attachment-count value` |
| `--attachment-dir` | | string | attachments | directory to save attachments | `mailos search --attachment-dir value` |
| `--attachment-name` | | string | | Filter by attachment filename (supports wildcards) | `mailos search --attachment-name value` |
| `--attachment-size` | | string | | Minimum attachment size (e.g., '1MB') | `mailos search --attachment-size value` |
| `--body-contains` | | string | | Search for specific text in email body | `mailos search --body-contains value` |
| `--body-length` | | string | | Filter by body length in characters | `mailos search --body-length value` |
| `--business-hours` | | bool | false | Only show emails sent during business hours (9-5) | `mailos search --business-hours` |
| `--case-sensitive` | | bool | false | Enable case sensitive search | `mailos search --case-sensitive` |
| `--conversation-length` | | int | 0 | Filter by minimum conversation/thread length | `mailos search --conversation-length value` |
| `--conversation-start` | | bool | false | Filter emails that start conversations | `mailos search --conversation-start` |
| `--date-range` | | string | | Flexible date range (e.g., 'today', 'last week', '2023-01-01 to 2023-12-31') | `mailos search --date-range value` |
| `--dkim-status` | | string | | Filter by DKIM verification status (pass, fail) | `mailos search --dkim-status value` |
| `--dmarc-status` | | string | | Filter by DMARC verification status (pass, fail) | `mailos search --dmarc-status value` |
| `--domain` | | string | | Filter by sender domain (e.g., 'gmail.com') | `mailos search --domain value` |
| `--download-attachments` | | bool | false | download email attachments | `mailos search --download-attachments` |
| `--encoding` | | string | | Filter by email encoding (e.g., 'utf-8', 'iso-8859-1') | `mailos search --encoding value` |
| `--encrypted` | | bool | false | Filter encrypted emails | `mailos search --encrypted` |
| `--exact` | | bool | false | Match exact phrases only (no fuzzy matching) | `mailos search --exact` |
| `--exact-subject` | | bool | false | match subject exactly (no fuzzy matching) | `mailos search --exact-subject` |
| `--exclude-domains` | | \[]string | | Exclude emails from specific domains | `mailos search --exclude-domains value` |
| `--explain` | | bool | false | Explain search strategy and applied filters | `mailos search --explain` |
| `--external-only` | | bool | false | Only show emails from external domains | `mailos search --external-only` |
| `--extract-emails` | | \[]string | | Extract and filter email addresses from body | `mailos search --extract-emails value` |
| `--extract-phones` | | \[]string | | Extract and filter phone numbers from body | `mailos search --extract-phones value` |
| `--extract-urls` | | \[]string | | Extract and filter URLs from email body | `mailos search --extract-urls value` |
| `--filetype` | | string | | Filter by attachment file type (e.g., 'pdf', 'jpg', 'docx') | `mailos search --filetype value` |
| `--filetypes` | | \[]string | | Filter by multiple attachment file types (e.g., 'pdf,docx,xlsx') | `mailos search --filetypes value` |
| `--first` | | bool | false | Get the oldest email (sorts by date ascending, limits to 1, shows full content) | `mailos search --first` |
| `--from-domain` | | string | | Filter by sender domain | `mailos search --from-domain value` |
| `--from-file` | | string | | Path to CSV/text file containing email addresses to filter by (searches emails FROM these addresses) | `mailos search --from-file value` |
| `--from-file-column` | | string | | Column name in CSV to extract emails from (default: auto-detect 'email' column) | `mailos search --from-file-column value` |
| `--fuzzy-threshold` | | float64 | 0.7 | Fuzzy matching threshold (0.0-1.0) | `mailos search --fuzzy-threshold value` |
| `--has-attachments` | | bool | false | Filter emails with attachments | `mailos search --has-attachments` |
| `--has-bcc` | | bool | false | Filter emails with BCC recipients | `mailos search --has-bcc` |
| `--has-cc` | | bool | false | Filter emails with CC recipients | `mailos search --has-cc` |
| `--has-reply-to` | | bool | false | Filter emails with Reply-To header | `mailos search --has-reply-to` |
| `--html-only` | | bool | false | Only search HTML emails | `mailos search --html-only` |
| `--importance` | | string | | Filter by email importance (high, normal, low) | `mailos search --importance value` |
| `--in-reply-to` | | string | | Search by In-Reply-To header | `mailos search --in-reply-to value` |
| `--internal-only` | | bool | false | Only show emails from internal/same domain | `mailos search --internal-only` |
| `--is-forward` | | bool | false | Filter forwarded emails | `mailos search --is-forward` |
| `--is-reply` | | bool | false | Filter emails that are replies | `mailos search --is-reply` |
| `--last` | | bool | false | Get the most recent email (sorts by date descending, limits to 1, shows full content) | `mailos search --last` |
| `--latest` | | bool | false | Alias for --recent (sorts by date descending) | `mailos search --latest` |
| `--line-count` | | int | 0 | Filter by minimum number of lines in body | `mailos search --line-count value` |
| `--mailbox` | | string | Inbox | Mailbox to search when using Apple Mail source | `mailos search --mailbox value` |
| `--max-size` | | string | | Maximum email size (e.g., '10MB', '2GB') | `mailos search --max-size value` |
| `--message-id` | | string | | Search by Message-ID header | `mailos search --message-id value` |
| `--min-size` | | string | | Minimum email size (e.g., '1MB', '500KB') | `mailos search --min-size value` |
| `--month` | | string | | Filter by month (e.g., 'january', '01') | `mailos search --month value` |
| `--newer-than-days` | | int | 0 | Filter emails newer than N days | `mailos search --newer-than-days value` |
| `--no-attachments` | | bool | false | Filter emails without attachments | `mailos search --no-attachments` |
| `--no-auto-sync` | | bool | false | Disable automatic sync when data is stale (over 1 day old) | `mailos search --no-auto-sync` |
| `--no-fuzzy` | | bool | false | Disable fuzzy matching | `mailos search --no-fuzzy` |
| `--no-spam` | | bool | false | Exclude emails marked as spam | `mailos search --no-spam` |
| `--older-than-days` | | int | 0 | Filter emails older than N days | `mailos search --older-than-days value` |
| `--phone` | | string | | Search by phone number (format-insensitive: spaces, country code, punctuation) | `mailos search --phone value` |
| `--priority` | | string | | Filter by email priority (high, normal, low) | `mailos search --priority value` |
| `--query` | `-q` | string | | Complex search query with boolean operators (AND, OR, NOT) | `mailos search --query value` |
| `--range` | | string | | time range (e.g., 'last hour', 'today', 'yesterday', 'this week') | `mailos search --range value` |
| `--recent` | | bool | false | Show recent emails (sorts by date descending) | `mailos search --recent` |
| `--resync` | | bool | false | Resync emails from server before searching | `mailos search --resync` |
| `--signed` | | bool | false | Filter digitally signed emails | `mailos search --signed` |
| `--sort-by` | | string | date | Sort results by (date, sender, subject, size, relevance) | `mailos search --sort-by value` |
| `--sort-order` | | string | desc | Sort order (asc, desc) | `mailos search --sort-order value` |
| `--source` | | string | | Email source: 'imap' (default), 'applemail' (read from Mail.app) | `mailos search --source value` |
| `--spam` | | bool | false | Include emails marked as spam | `mailos search --spam` |
| `--spf-status` | | string | | Filter by SPF verification status (pass, fail, neutral) | `mailos search --spf-status value` |
| `--subject-length` | | string | | Filter by subject length (e.g., '>50', '<20', '10-100') | `mailos search --subject-length value` |
| `--suggestions` | | bool | false | Show smart query suggestions after results | `mailos search --suggestions` |
| `--sync-from` | | string | | Sync emails from specific date (e.g., '2023-01-01', 'last week', 'yesterday') | `mailos search --sync-from value` |
| `--sync-range` | | string | | Sync emails for date range (e.g., '2023-01-01 to 2023-12-31') | `mailos search --sync-range value` |
| `--sync-until` | | string | | Sync emails until specific date | `mailos search --sync-until value` |
| `--text-only` | | bool | false | Only search plain text emails | `mailos search --text-only` |
| `--thread` | | bool | false | Group results by inferred conversation thread | `mailos search --thread` |
| `--thread-id` | | string | | Search by thread/conversation ID | `mailos search --thread-id value` |
| `--time-range` | | string | | Filter by time of day (e.g., '09:00-17:00') | `mailos search --time-range value` |
| `--to-domain` | | string | | Filter by recipient domain | `mailos search --to-domain value` |
| `--unique-senders` | | bool | false | Show only unique senders (deduplicate by sender) | `mailos search --unique-senders` |
| `--unique-subjects` | | bool | false | Show only unique subjects (deduplicate by subject) | `mailos search --unique-subjects` |
| `--view` | | string | normal | Output view profile (compact, normal, full) | `mailos search --view value` |
| `--weekday` | | string | | Filter by day of week (e.g., 'monday', 'weekend') | `mailos search --weekday value` |
| `--word-count` | | int | 0 | Filter by minimum word count in body | `mailos search --word-count value` |
| `--year` | | string | | Filter by year (e.g., '2023') | `mailos search --year value` |
### Output Options
| Flag | Short | Type | Default | Description | Example |
|------|-------|------|---------|-------------|---------|
| `--count-only` | `-c` | bool | false | Show only count of matching emails | `mailos search --count-only` |
| `--full-content` | | bool | false | Display full email content instead of snippets | `mailos search --full-content` |
| `--include-headers` | | bool | false | Include full email headers in output | `mailos search --include-headers` |
| `--output-dir` | | string | emails | directory to save markdown files | `mailos search --output-dir value` |
| `--save-markdown` | | bool | false | save emails as markdown files | `mailos search --save-markdown` |
## Query Syntax Options
### CLI Flags (Structured)
Use individual flags for structured searches:
```bash
# Structured approach using flags
mailos search --from "boss" --subject "urgent" --days 7
mailos search --has-attachments --min-size 1MB --type inbox
```
### Direct Notmuch Query (Advanced)
For users familiar with Notmuch, you can use direct query syntax:
```bash
# Direct Notmuch query syntax
mailos search "from:boss AND subject:urgent AND date:7days.."
mailos search "date:yesterday.. AND from:manager@company.com"
mailos search "tag:attachment AND date:2024-01-01.."
# Complex Notmuch queries
mailos search "(from:client1.com OR from:client2.com) AND date:this_month"
mailos search "subject:invoice AND NOT tag:spam"
```
**Note**: Direct Notmuch queries bypass CLI flag processing and use Notmuch's native syntax. This provides maximum flexibility for advanced users but requires knowledge of Notmuch query syntax.
### Boolean Operators
* **AND**: All terms must match (default)
```bash
mailos search -q "urgent AND project AND deadline"
```
* **OR**: Any term can match
```bash
mailos search -q "invoice OR billing OR payment"
```
* **NOT**: Exclude terms
```bash
mailos search -q "meeting NOT cancelled"
```
### Field-Specific Search
Target specific email fields:
```bash
# Search in sender field
mailos search -q "from:support"
# Search in recipient field
mailos search -q "to:team@company.com"
# Search in subject line
mailos search -q "subject:urgent"
# Search in email body
mailos search -q "body:confidential"
```
### Exact Phrase Matching
#### Using the --exact Flag
Use the `--exact` flag for precise phrase matching without fuzzy search:
```bash
# Find exact phrase "next day"
mailos search "next day" --exact
# Exact phrase in subject field
mailos search --subject "meeting tomorrow" --exact
# Compare fuzzy vs exact matching
mailos search "daily report" # Fuzzy matching (finds "dayly report", "daily reports")
mailos search "daily report" --exact # Exact phrase only
# Exact search with other filters
mailos search "contract terms" --exact --has-attachments
```
#### Using Query Quotes
Alternatively, use quotes within queries for exact phrases:
```bash
# Exact phrase in query (disables fuzzy matching)
mailos search -q '"urgent: please reply immediately"'
# Mixed exact and fuzzy
mailos search -q '"project alpha" AND deadline'
```
### Complex Query Examples
```bash
# Multiple conditions with field targeting
mailos search -q "from:manager AND (urgent OR important) AND NOT spam"
# Date range with boolean search
mailos search -q "invoice OR billing" --date-range "last month"
# Size and content filters combined
mailos search -q "contract OR agreement" --min-size 100KB --has-attachments
```
## Fuzzy Search
Fuzzy search helps find emails even with typos or slight variations:
### How It Works
* Uses Levenshtein distance algorithm
* Configurable similarity threshold (0.0 to 1.0)
* Default threshold: 0.7 (70% similarity)
### Examples
```bash
# Find "support" even if typed as "supprt"
mailos search --from "supprt"
# Adjust fuzzy sensitivity
mailos search --fuzzy-threshold 0.5 --from "suport"
# Disable fuzzy matching for exact searches
mailos search --no-fuzzy --from "support@company.com"
```
### Fuzzy Threshold Guide
* **0.9-1.0**: Very strict (minor typos only)
* **0.7-0.8**: Balanced (default, handles common typos)
* **0.5-0.6**: Loose (more variations accepted)
* **0.0-0.4**: Very loose (may match unrelated terms)
## Date Range Examples
### Natural Language Dates
```bash
mailos search --date-range "today"
mailos search --date-range "yesterday"
mailos search --date-range "last week"
mailos search --date-range "this month"
mailos search --date-range "last month"
mailos search --date-range "this year"
```
### Specific Date Ranges
```bash
mailos search --date-range "2023-01-01 to 2023-12-31"
mailos search --date-range "2024-06-01 to 2024-06-30"
```
### Relative Dates
```bash
mailos search --date-range "last 7 days"
mailos search --date-range "last 30 days"
mailos search --date-range "last 90 days"
```
## Size Filter Examples
### Email Size Filtering
```bash
# Large emails only
mailos search --min-size 1MB
# Small to medium emails
mailos search --max-size 500KB
# Specific size range
mailos search --min-size 100KB --max-size 5MB
```
### Attachment Filtering
```bash
# Emails with any attachments
mailos search --has-attachments
# Emails with large attachments
mailos search --attachment-size 1MB
# Combined attachment and size filters
mailos search --has-attachments --min-size 2MB
```
## Practical Use Cases
### Finding Important Communications
```bash
# Urgent emails from management with alias authentication
mailos search --account work@company.com -q "from:manager AND (urgent OR important OR asap)"
# Contract-related emails with attachments from specific domains
mailos search -q "contract OR agreement" --has-attachments --min-size 50KB --from-domain client.com
# High-priority encrypted emails
mailos search --priority high --encrypted --importance high
# External communications only
mailos search --external-only --has-cc --business-hours
```
### Email Cleanup and Management
```bash
# Large emails consuming storage (over 10MB)
mailos search --min-size 10MB --sort-by size --sort-order desc
# Old promotional emails with specific content
mailos search -q "unsubscribe OR newsletter" --date-range "last 6 months" --exclude-domains important.com
# Emails with large attachments for archival
mailos search --attachment-size 5MB --date-range "last year" --filetype pdf
# HTML-only emails with no attachments (potential spam)
mailos search --html-only --no-attachments --external-only
# Use suggestions to discover search patterns
mailos search --from "newsletter" --suggestions
```
### Advanced Security and Compliance Analysis
```bash
# Failed email authentication checks
mailos search --spf-status fail --dkim-status fail
# Digitally signed emails from external sources
mailos search --signed --external-only --importance high
# Conversation threads with multiple participants
mailos search --conversation-length 5 --has-cc --has-bcc
```
### Project and Work Tracking
```bash
# Project-related communications with threading analysis
mailos search -q "project:alpha OR alpha-project" --date-range "this month" --conversation-start
# Invoice and billing emails with verification
mailos search -q "invoice OR billing OR payment" --has-attachments --filetype pdf,docx
# Client communications during business hours
mailos search --from-domain client.com --business-hours --is-reply
# Extract contact information from emails
mailos search --extract-emails --extract-phones --body-contains "contact"
```
### Content Analysis and Data Mining
```bash
# Long-form emails with substantial content
mailos search --word-count 500 --line-count 20 --body-length ">2000"
# Emails with specific file types and URLs
mailos search --filetypes pdf,xlsx,pptx --extract-urls
# Threaded conversations about specific topics
mailos search -q "budget OR financial" --is-reply --thread-id "specific-thread"
```
## Smart Query Suggestions
Use the `--suggestions` flag to get intelligent query recommendations based on your email patterns:
```bash
# Get suggestions after search results
mailos search --from "work" --suggestions
mailos search --has-attachments --suggestions
# Get suggestions with verbose analysis
mailos search --suggestions --verbose
```
**Suggestion Types:**
* **Sender patterns**: Frequent email contacts
* **Domain analysis**: Common domains in your email
* **Subject keywords**: Frequent subject terms
* **Date ranges**: Common time-based searches
* **Filter combinations**: Suggested advanced filters
## Performance Tips
1. **Use specific filters** to reduce search scope
2. **Combine date ranges** with other filters for faster results
3. **Adjust fuzzy threshold** based on your needs
4. **Use field-specific searches** when possible
5. **Limit result count** with `-n` flag
6. **Use --exact for precise matching** when you know exact terms
7. **Try direct Notmuch queries** for complex searches
8. **Enable --verbose mode** to see performance metrics and optimization hints
## Troubleshooting
### Search Returns No Results
1. Check query syntax with simple terms first
2. Try lowering fuzzy threshold: `--fuzzy-threshold 0.5`
3. Verify date ranges are correct
4. Remove filters one by one to isolate issues
5. Use `--resync` to ensure latest emails are cached
### Content Not Displaying with --full-content
1. Verify email has actual body content (not header-only)
2. Try without other filters to isolate the issue
3. Check if email is multipart/mixed format requiring HTML parsing
4. Use `--verbose` mode to see extraction details
5. Ensure cache is updated with `--resync` if content was recently modified
### Fuzzy Search Too Broad
1. Increase fuzzy threshold: `--fuzzy-threshold 0.8`
2. Use exact phrases with quotes or `--exact` flag
3. Enable case sensitivity: `--case-sensitive`
4. Disable fuzzy matching: `--no-fuzzy`
5. Try direct Notmuch query syntax for precise control
### Size Filters Not Working
1. Verify size units (B, KB, MB, GB, TB)
2. Check that emails have been synced locally
3. Use broader size ranges initially
### Boolean Queries Not Working
1. Ensure proper spacing around operators
2. Use quotes for phrases containing operators
3. Check parentheses for complex queries
4. Start with simple AND/OR queries
## Integration with Other Commands
### Combining with Read Command
```bash
# Search to find email IDs, then read specific emails
mailos search -q "important contract" --json | jq '.[].id'
mailos read 12345 # Read specific email by ID
```
### Saving Search Results
```bash
# Save search results to files
mailos search -q "quarterly report" --save-markdown --output-dir ./reports
# Export search results as JSON
mailos search --date-range "last month" --json > last_month_emails.json
```
## Content Display Options
### Full Content Display
The `--full-content` flag provides comprehensive email content extraction:
```bash
# Display complete email content instead of snippets
mailos search --from "invoice@company.com" --full-content
# Full content with multipart HTML email support
mailos search --body-contains "contract" --full-content --html-only
# Complex invoice emails with nested HTML structure
mailos search --from "quickbooks" --full-content --has-attachments
```
**Full Content Features:**
* **HTML Priority**: Automatically extracts HTML content when available, falls back to plain text
* **Multipart Support**: Handles complex multipart/mixed emails (invoices, newsletters, etc.)
* **Cache Differentiation**: Full content searches use separate cache keys to ensure proper content display
* **Performance**: Content extraction adds minimal overhead compared to header-only searches
### Content Parsing Capabilities
The search system now handles sophisticated email structures:
* **Plain Text Emails**: Direct content extraction
* **HTML Emails**: Full HTML content with proper parsing
* **Multipart/Mixed**: Complex nested structures common in business emails
* **Invoice Emails**: Specialized parsing for QuickBooks and similar invoice systems
* **Newsletter Content**: Rich HTML newsletters with embedded images and styling
## Caching and Performance
The search command uses a local email cache for fast searching:
* **Local Cache**: Emails are cached locally in a global inbox for fast search
* **Content-Aware Caching**: Separate cache entries for header-only vs full-content searches
* **Sync Status**: Shows last sync time and warns if cache is stale (>1 hour old)
* **Performance**: Cache searches are 20-50x faster than IMAP searches
* **Auto-sync**: Use `--resync` to update cache with latest emails
### Cache Management
```bash
# Check cache status
mailos search # Shows last sync time
# Update cache with latest emails
mailos search --resync
# Sync specific date range
mailos search --sync-from "last week"
mailos search --sync-range "2023-01-01 to 2023-12-31"
```
## Notes
* Search primarily uses cached emails for performance
* Use `--resync` to fetch latest emails from server
* Fuzzy matching works on all text fields (from, to, subject, body)
* Size calculations include email content and attachments
* Date ranges use your local timezone
* Boolean operators are case-insensitive (AND, and, And all work)
* Search results are sorted by date (newest first)
* Email IDs from search results can be used with `mailos read` command
---
---
url: /reply.md
---
# Reply Command
Reply to emails while preserving thread context and conversation history.
## Usage
```bash
# Method 1: Using email ID from search results
mailos reply [email_id] [flags]
# Method 2: Using email title and sender (exact matching)
mailos reply --email-title "Subject" --from "sender@example.com" [flags]
```
## Description
The `reply` command allows you to respond to specific emails while maintaining proper email threading. Unlike the `send` command which creates new emails, `reply` ensures your response becomes part of the existing conversation thread.
## Email Identification Methods
### Method 1: Using Email ID (Recommended)
The `email_id` parameter uses the actual IMAP message ID shown in search results:
```bash
# First, search for emails to see available IDs
mailos search --from john@example.com
# Output shows: ID: 20691, ID: 18432, etc.
# Reply using the specific email ID
mailos reply 20691 --body "Thanks for the update!"
mailos reply 18432 --body "I'll be there at 10am"
```
### Method 2: Using Email Title and Sender (New!)
For exact matching by subject and sender email address:
```bash
# Reply to specific email by exact title and sender
mailos reply --email-title "Project Update" --from "john@example.com" --body "Received!"
# Create draft reply using title/sender matching
mailos reply --email-title "Meeting Request" --from "manager@company.com" --draft --body "I'll attend"
```
**Important:**
* Email title matching is **exact** (case-insensitive)
* Sender matching uses just the email address, not the display name
* Both `--email-title` and `--from` flags must be provided together
## Threading Behavior
The reply command automatically:
* **Preserves conversation threads** by setting proper email headers (`In-Reply-To`, `References`)
* **Maintains subject line** with "Re:" prefix if not already present
* **Sets correct recipients** (reply to sender, or reply-all to all recipients)
* **Includes original message context** in interactive mode
## Flags
### Basic Options
* `--body string` - Reply body text
* `--subject string` - Override reply subject (keeps "Re:" prefix)
* `-f, --file string` - Read body content from file
* `-i, --interactive` - Force interactive composition mode
### Email Selection (New!)
* `--email-title string` - Find email by exact subject/title (use with --from)
* `--from string` - Find email from specific sender (use with --email-title)
### Recipient Options
* `--all` - Reply to all recipients (reply-all)
* `--to strings` - Override recipients
* `--cc strings` - Add CC recipients
* `--bcc strings` - Add BCC recipients
### Draft Options
* `--draft` - Save as draft instead of sending immediately
## Examples
### Basic Reply (Using Email ID)
```bash
# Interactive reply using email ID from search
mailos reply 20691
# Quick reply with message
mailos reply 18432 --body "Thanks for your email!"
# Reply with custom subject
mailos reply 15234 --subject "Re: Updated timeline" --body "Looks good"
```
### Basic Reply (Using Title/Sender - New!)
```bash
# Reply using exact title and sender matching
mailos reply --email-title "Hello" --from "user@gmail.com" --body "4x5 = 20"
# Reply to meeting invite
mailos reply --email-title "Team Meeting" --from "boss@company.com" --body "I'll be there"
# Reply with custom subject override
mailos reply --email-title "Project Update" --from "john@example.com" --subject "Re: Revised timeline" --body "Approved"
```
### Reply All
```bash
# Reply to all recipients using email ID
mailos reply 20691 --all --body "Thanks everyone for the feedback"
# Reply all using title/sender with additional CC
mailos reply --email-title "Team Update" --from "manager@company.com" --all --cc team@company.com --body "Looping in the team"
```
### File-based Reply
```bash
# Read reply content from file using email ID
mailos reply 18432 --file response.txt
# Using title/sender with file content
mailos reply --email-title "Support Request" --from "customer@example.com" --file template.txt --cc support@company.com
```
### Draft Mode
```bash
# Save reply as draft using email ID
mailos reply 20691 --body "Draft response" --draft
# Create draft using title/sender matching
mailos reply --email-title "Invoice" --from "billing@vendor.com" --body "Payment processed" --draft
# Create draft reply-all
mailos reply 15234 --all --body "Team update" --draft
```
### Advanced Examples
```bash
# Override all recipients using email ID
mailos reply 20691 --to different@example.com --body "Forwarding to you"
# Reply with BCC using title/sender matching
mailos reply --email-title "Bug Report" --from "developer@company.com" --body "Will handle this" --bcc manager@company.com
# Interactive reply all with custom subject
mailos reply --email-title "Proposal" --from "client@company.com" --all --subject "Re: Revised proposal" --interactive
```
## Interactive Mode
When no `--body` or `--file` is specified, or when `--interactive` is used, the reply command enters interactive mode:
1. Shows original email context
2. Opens composition interface
3. Automatically includes quoted original message
4. Press Enter twice to finish composition
```bash
mailos reply 1 --interactive
```
Output:
```
📧 Replying to: Project Update
From: john@example.com
Date: Oct 18, 2025 at 2:30 PM
Message-ID:
────────────────────────────────────────────
📝 Compose your reply:
(Press Enter twice to finish)
────────────────────────────────────────────
Thanks for the update!
[Your message here]
✓ Reply sent successfully!
```
## Threading Details
### Message Headers
The reply command automatically sets these headers for proper threading:
* **In-Reply-To**: ``
* **References**: Chain of Message-IDs in the conversation
* **Subject**: "Re: Original Subject" (if not already prefixed)
### Conversation Chains
For multi-reply conversations:
```
Original Email:
├── Reply 1: References:
├── Reply 2: References:
└── Reply 3: References:
```
## Error Handling
Common errors and solutions:
```bash
# Email ID not found
Error: email 'with UID 99999' not found
# Solution: Use correct email ID from search results
# Email title/sender not found (using new method)
No emails found with exact title 'Wrong Title' from 'wrong@example.com'
# Solution: Check exact spelling and sender address
# Missing required flags for title/sender method
Error: email identifier required
# Solution: Use either email_id OR both --email-title and --from flags
# Invalid email ID
Error: invalid email number: abc
# Solution: Use numeric email ID from search results
```
## Integration with Other Commands
### Typical Workflow (Method 1: Email ID)
```bash
# 1. Search for emails to see available IDs
mailos search --from important@client.com
# Output: ID: 20691, ID: 18432, etc.
# 2. Read specific email for context using the ID
mailos read 20691
# 3. Reply to the email using the same ID
mailos reply 20691 --body "Thanks for reaching out!"
# 4. Check drafts or sent emails
mailos search --type sent
```
### Alternative Workflow (Method 2: Title/Sender)
```bash
# 1. If you know the exact email title and sender
mailos reply --email-title "Hello" --from "user@gmail.com" --body "Hi there!"
# 2. For emails you can't find by ID
mailos reply --email-title "Meeting Confirmation" --from "calendar@company.com" --draft --body "Confirmed"
```
### Draft Workflow
```bash
# Create reply draft
mailos reply 2 --body "Initial response" --draft
# Edit the draft later
mailos draft edit 1 --body "Updated response"
# Send the draft
mailos send --drafts
```
## Tips
1. **Use Email IDs**: Use `mailos search` to get email IDs, then use those IDs with `mailos reply`
2. **Title/Sender Method**: Use `--email-title` and `--from` when you know exact subject and sender
3. **Exact Matching**: Email title matching is case-insensitive but must be exact
4. **Use Read**: Use `mailos read [email_id]` to view full email content before replying
5. **Draft for Review**: Use `--draft` for important replies that need review
6. **Reply-All Carefully**: Double-check recipients when using `--all` flag
7. **File Templates**: Create reusable response templates with `--file` option
## See Also
* [`mailos search`](search.md) - Find emails to reply to
* [`mailos read`](read.md) - View email content before replying
* [`mailos send`](send.md) - Send new emails (non-threaded)
* [`mailos draft`](drafts.md) - Manage email drafts
* [`mailos sent`](sent.md) - View sent emails
---
---
url: /forward.md
---
# Forward Command
Forward a specific email to one or more recipients.
## Synopsis
```bash
mailos forward [email_number] [flags]
```
## Description
The forward command allows you to forward a specific email from your inbox to one or more recipients. You can specify the email by its number (as shown in `mailos search` results), by its UID, or by its Message-ID.
The forwarded email includes the original message content with proper attribution, similar to standard email client forwarding behavior.
## Options
```
-a, --account string Email account to use
--bcc strings BCC recipients
--body string Custom body text for the forward
--cc strings CC recipients
--draft Save as draft instead of sending
--file-body string Read body text from file
-h, --help Help for forward
-i, --interactive Interactive composition mode
--message-id string Message-ID to forward
--number int Email number to forward
--subject string Custom subject for forward
--to strings To recipients
--uid uint32 Email UID to forward
```
## Examples
### Basic Forward
Forward email #2 to a single recipient:
```bash
mailos forward 2 --to user@example.com
```
### Forward to Multiple Recipients
Forward email #2 to multiple recipients:
```bash
mailos forward 2 --to user1@example.com,user2@example.com
```
### Forward with Custom Message
Forward email #2 with additional message:
```bash
mailos forward 2 --to user@example.com --body "FYI - thought you'd find this interesting"
```
### Forward with CC and BCC
Forward email #2 with CC and BCC recipients:
```bash
mailos forward 2 --to user@example.com --cc manager@example.com --bcc archive@example.com
```
### Save Forward as Draft
Save the forward as a draft instead of sending immediately:
```bash
mailos forward 2 --to user@example.com --draft
```
### Interactive Forward
Compose the forward message interactively:
```bash
mailos forward 2 --to user@example.com --interactive
```
### Forward by UID
Forward an email by its IMAP UID:
```bash
mailos forward --uid 1234 --to user@example.com
```
### Forward by Message-ID
Forward an email by its Message-ID:
```bash
mailos forward --message-id "" --to user@example.com
```
### Forward with File Body
Include message from a file:
```bash
mailos forward 2 --to user@example.com --file-body message.txt
```
## Output
The command provides feedback on the forwarding process:
```
📧 Forwarding: Subject of Original Email
From: original-sender@example.com
Date: Jan 2, 2006 at 3:04 PM
Message-ID:
📤 Sending forward...
✓ Forward sent successfully!
```
If saving as draft:
```
✓ Forward saved as draft (UID: 5678)
```
## Behavior
### Forward Format
The forwarded email includes:
* Your custom message (if provided)
* A standard Apple Mail-style marker: "Begin forwarded message:"
* Original email headers (From, Subject, Date, To, Reply-To when available)
* Original email body
### Email Identification
You can identify emails to forward using:
1. **Email number**: As shown in `mailos search` output (most common)
2. **UID**: IMAP unique identifier
3. **Message-ID**: RFC 5322 Message-ID header
### Subject Handling
* If the original subject doesn't start with "Fwd:" or "Fw:", the prefix "Fwd: " is automatically added
* You can override the subject completely using `--subject`
### Interactive Mode
In interactive mode:
* You can compose a custom message before the forwarded content
* Type your message and press Enter twice to finish
* The original message is automatically appended
### Draft Mode
When using `--draft`:
* The forward is saved both locally and to your IMAP Drafts folder
* You can send it later using `mailos send --drafts`
* The draft includes all recipients and content
## Error Handling
Common errors and solutions:
### Email Not Found
```
failed to find email #123: email with ID 123 not found
```
* Verify the email number using `mailos search`
* Ensure you're connected to the correct account
### Missing Recipients
```
must specify either email number, UID, or Message-ID to forward
```
* Provide at least one method to identify the email
* Use `--to` flag to specify recipients
### Authentication Issues
```
failed to authenticate: invalid credentials
```
* Check your email credentials with `mailos setup`
* Ensure app-specific passwords are configured if using 2FA
## Related Commands
* `mailos search` - Find emails to forward
* `mailos read` - View email content before forwarding
* `mailos reply` - Reply to an email instead of forwarding
* `mailos send` - Send composed emails or drafts
* `mailos drafts` - Manage draft emails
---
---
url: /drafts.md
---
# Draft Management
The `mailos draft` command (alias for `drafts`) provides comprehensive draft email management with automatic synchronization to your email account's Drafts folder.
## Overview
Create, manage, and send draft emails with full IMAP synchronization. Drafts are saved both locally and to your email provider's Drafts folder, ensuring they're accessible from any email client.
## Basic Usage
```bash
# Create a single draft interactively
mailos draft --interactive
# Create multiple drafts (alias)
mailos drafts --interactive
# List drafts from IMAP Drafts folder
mailos draft --list
# Read full draft content from IMAP
mailos draft --read
# Generate drafts with AI
mailos draft --ai "create follow-up email for meeting" --count 3
# Send all drafts
mailos send --drafts
```
## Command-Line Flags
### Basic Options
| Flag | Short | Type | Default | Description | Example |
|------|-------|------|---------|-------------|---------|
| `--account` | | string | | Email account to use | `mailos drafts --account value` |
| `--bcc` | `-B` | \[]string | | BCC recipients | `mailos drafts --bcc value` |
| `--body` | `-b` | string | | Email body (Markdown supported) | `mailos drafts --body value` |
| `--cc` | `-c` | \[]string | | CC recipients | `mailos drafts --cc value` |
| `--subject` | `-s` | string | | Email subject | `mailos drafts --subject value` |
| `--to` | `-t` | \[]string | | Recipient email addresses | `mailos drafts --to value` |
### Advanced Options
| Flag | Short | Type | Default | Description | Example |
|------|-------|------|---------|-------------|---------|
| `--ai` | | bool | false | Use AI to generate drafts from query | `mailos drafts --ai` |
| `--attach` | `-a` | \[]string | | Attachments | `mailos drafts --attach value` |
| `--count` | `-n` | int | 1 | Number of drafts to generate (with AI) | `mailos drafts --count value` |
| `--data` | | string | | Data file (CSV/JSON) for bulk draft generation | `mailos drafts --data value` |
| `--edit-uid` | | uint32 | 0 | UID of existing draft to edit/update | `mailos drafts --edit-uid value` |
| `--file` | `-f` | string | | Read body from file | `mailos drafts --file value` |
| `--force` | | bool | false | Force create draft bypassing dynamic content warnings | `mailos drafts --force` |
| `--interactive` | `-i` | bool | false | Interactive mode for creating drafts | `mailos drafts --interactive` |
| `--list` | `-l` | bool | false | List drafts from IMAP Drafts folder | `mailos drafts --list` |
| `--no-signature` | `-S` | bool | false | Don't add signature | `mailos drafts --no-signature` |
| `--plain` | `-P` | bool | false | Send as plain text only | `mailos drafts --plain` |
| `--priority` | | string | normal | Email priority (high/normal/low) | `mailos drafts --priority value` |
| `--read` | `-r` | bool | false | Read full content of drafts from IMAP | `mailos drafts --read` |
| `--replace` | | \[]string | | Replace dynamic content with KEY=VALUE pairs (e.g., --replace USER\_NAME=John --replace DATE=2024-01-01) | `mailos drafts --replace value` |
| `--signature` | | string | | Custom signature | `mailos drafts --signature value` |
| `--template` | | string | | Use a template for draft generation | `mailos drafts --template value` |
### Output Options
| Flag | Short | Type | Default | Description | Example |
|------|-------|------|---------|-------------|---------|
| `--output` | | string | | Output directory for drafts (default: ~/.email/drafts) | `mailos drafts --output value` |
## Key Features
### 📮 Automatic IMAP Synchronization
* Drafts are automatically saved to your email account's Drafts folder
* Compatible with Gmail, Outlook, Yahoo, and other IMAP providers
* Drafts appear instantly in your email client
* Proper RFC 822 email format with `\Draft` IMAP flag
### 📝 Local and Remote Storage
* Local files saved to `draft-emails/` directory
* Remote copies in your email provider's Drafts folder
* Dual storage provides backup and cross-device access
### 🎯 Smart Draft Detection
* Automatically detects the correct Drafts folder name
* Handles provider-specific folders (\[Gmail]/Drafts, INBOX.Drafts, etc.)
* Creates Drafts folder if it doesn't exist
## Command Options
```bash
mailos draft [options]
```
| Option | Description |
|--------|-------------|
| `--list`, `-l` | List drafts from IMAP Drafts folder |
| `--read`, `-r` | Read full content of drafts from IMAP |
| `--interactive`, `-i` | Create drafts interactively with prompts |
| `--ai` | Use AI to generate drafts from a query |
| `--count N`, `-n N` | Number of drafts to generate (with AI) |
| `--template STRING` | Use a template for draft generation |
| `--data FILE` | Data file (CSV/JSON) for bulk generation |
| `--output DIR` | Output directory (default: "draft-emails") |
## Draft File Format
Drafts are saved as Markdown files with YAML frontmatter:
```markdown
---
to: recipient@example.com
cc: cc@example.com
bcc: bcc@example.com
subject: Meeting Follow-up
priority: high
send_after: 2024-01-15 09:00:00
attachments:
- report.pdf
- presentation.pptx
---
Dear Team,
Following up on our meeting yesterday...
Best regards,
Your Name
```
## Sending Drafts
### Send All Drafts
```bash
mailos send --drafts
```
### Preview Before Sending
```bash
mailos send --drafts --dry-run
```
### Filter by Priority
```bash
# Only send high priority drafts
mailos send --drafts --filter="priority:high"
```
### Filter by Recipient
```bash
# Only send to specific domain
mailos send --drafts --filter="to:*@company.com"
```
### Additional Send Options
```bash
# Confirm each draft before sending
mailos send --drafts --confirm
# Keep drafts after sending
mailos send --drafts --delete-after=false
# Log sent emails
mailos send --drafts --log-file="sent.log"
```
## Reading Drafts from IMAP
### List All Drafts
```bash
# Show draft headers (subject, to, date)
mailos draft --list
```
### Read Full Draft Content
```bash
# Show complete draft with body content
mailos draft --read
```
The draft reader will:
* Connect to your email provider
* Automatically detect the Drafts folder
* Display all drafts with proper formatting
* Show flags (Draft, Seen, etc.)
* Format dates in readable format
## Interactive Draft Creation
When using `--interactive`, you'll be prompted for:
1. **To**: Primary recipient email address
2. **CC**: Carbon copy recipients (optional)
3. **Subject**: Email subject line
4. **Body**: Email content (Markdown supported)
5. **Priority**: high/normal/low (default: normal)
Press Enter twice after the body to finish.
## AI-Powered Draft Generation
```bash
# Generate drafts from natural language
mailos draft --ai "create 3 follow-up emails for recent client meetings"
# Specify number of drafts
mailos draft --ai "thank you email" --count 5
```
## Template-Based Drafts
```bash
# Use a template (coming soon)
mailos draft --template=follow-up --data=contacts.csv
```
## Draft Organization
```
draft-emails/
├── 001-meeting-follow-up-2024-01-15-143022.md
├── 002-project-update-2024-01-15-143045.md
├── 003-thank-you-2024-01-15-143102.md
├── sent/ # Successfully sent (if --delete-after=false)
│ └── 001-meeting-follow-up-2024-01-15-143022.md
└── failed/ # Failed to send
└── 003-thank-you-2024-01-15-143102.md
```
## IMAP Folder Detection
The system automatically detects your provider's Drafts folder:
| Provider | Common Folder Names |
|----------|-------------------|
| Gmail | \[Gmail]/Drafts |
| Outlook | Drafts |
| Yahoo | Draft |
| Fastmail | INBOX.Drafts |
| Generic | Drafts, Draft |
## Error Handling
* If IMAP save fails, local draft is still created
* Warning displayed but operation continues
* Drafts can still be sent using local files
## Examples
### Weekly Newsletter Draft
```bash
# Create draft interactively
mailos draft --interactive
# Enter details:
To: team@company.com
Subject: Weekly Update - Week 3
Body:
## This Week's Highlights
- Completed project milestone
- New team member onboarded
- Client meeting scheduled
# Draft saved locally and to email account
```
### Batch Follow-up Emails
```bash
# Create multiple drafts
mailos draft --interactive
# Answer 'y' when asked "Create another draft?"
# Review all drafts
ls draft-emails/
# Send with confirmation
mailos send --drafts --confirm
```
### Priority-Based Sending
```bash
# Create drafts with different priorities
mailos draft --interactive # Set priority: high
mailos draft --interactive # Set priority: normal
# Send only high priority
mailos send --drafts --filter="priority:high"
# Later, send normal priority
mailos send --drafts --filter="priority:normal"
```
## Troubleshooting
### Draft Not Appearing in Email Client
* Check your email client's Drafts folder
* Refresh/sync your email client
* Verify IMAP is enabled in your email settings
### IMAP Connection Failed
* Ensure app-specific password is configured
* Check IMAP is enabled for your account
* Verify network connectivity
### Drafts Folder Not Found
* System will attempt to create Drafts folder
* Falls back to INBOX if creation fails
* Local draft is always created successfully
## Best Practices
1. **Use Priority Levels**: Organize drafts by importance
2. **Preview Before Sending**: Always use `--dry-run` first
3. **Keep Backups**: Use `--delete-after=false` for important drafts
4. **Batch Similar Emails**: Create related drafts together
5. **Review IMAP Status**: Check for sync confirmation messages
## Related Commands
* `mailos send` - Send individual emails
* `mailos template` - Manage email templates
* `mailos interactive` - Interactive email mode
* `mailos read` - Read emails from inbox
## See Also
* [Send Command](send.md) - Detailed sending options
* [Template Management](template.md) - Create reusable templates
{/\* TODO: broken link removed — target page `interactive.md` does not exist in this repo. Restore once an Interactive Mode doc is added. \*/}
---
---
url: /sent.md
---
# EmailOS Sent Command Documentation
The `mailos sent` command retrieves and displays emails from your sent folder, allowing you to view emails you have previously sent.
## Basic Usage
```bash
mailos sent
```
Displays a list of your most recently sent emails with preview information.
## Command-Line Flags
### Basic Options
| Flag | Short | Type | Default | Description | Example |
|------|-------|------|---------|-------------|---------|
| `--account` | | string | | Account email to use (defaults to configured account) | `mailos sent --account value` |
| `--days` | | int | 0 | Show sent emails from last N days | `mailos sent --days value` |
| `--number` | `-n` | int | 10 | Number of sent emails to read | `mailos sent --number value` |
| `--subject` | | string | | Filter by subject | `mailos sent --subject value` |
| `--to` | | string | | Filter by recipient | `mailos sent --to value` |
### Advanced Options
| Flag | Short | Type | Default | Description | Example |
|------|-------|------|---------|-------------|---------|
| `--range` | | string | | Time range (e.g., 'Last hour', 'Today', 'Yesterday', 'This week') | `mailos sent --range value` |
### Output Options
| Flag | Short | Type | Default | Description | Example |
|------|-------|------|---------|-------------|---------|
| `--json` | | bool | false | Output as JSON | `mailos sent --json` |
| `--output-dir` | | string | resolved MailOS sent storage | Directory to save markdown files | `mailos sent --output-dir value` |
| `--save-markdown` | | bool | true | Save emails as markdown files | `mailos sent --save-markdown` |
## Examples
### View Recent Sent Emails
```bash
# Show last 10 sent emails
mailos sent
# Show last 20 sent emails
mailos sent -n 20
```
### Filter by Recipient
```bash
# Show emails sent to a specific person
mailos sent --to john@example.com
# Show emails sent to multiple people (search in To field)
mailos sent --to "@company.com"
```
### Filter by Subject
```bash
# Find sent emails about meetings
mailos sent --subject "meeting"
# Find sent emails with specific project name
mailos sent --subject "Project Alpha"
```
### Filter by Time Period
```bash
# Show emails sent in the last 7 days
mailos sent --days 7
# Show emails sent in the last 30 days
mailos sent --days 30
```
### Output Formats
```bash
# Get results in JSON format for scripting
mailos sent --json > sent-emails.json
# Disable markdown file saving
mailos sent --save-markdown=false
# Save to custom directory
mailos sent --output-dir ./my-sent-emails
```
### Multi-Account Usage
```bash
# Use specific account
mailos sent --account work@company.com
# View sent emails from personal account
mailos sent --account [PERSONAL_ACCOUNT]
```
## Output Format
The command displays sent emails with the following information:
* Email number (for reference)
* From address (your sending address)
* To address(es) (recipients)
* Subject line
* Date sent
* Email preview (first 100 characters)
* Attachment information (if any)
* Link to open email in desktop mail app
## Markdown File Storage
By default, sent emails are automatically saved as markdown files in `~/.email/sent/`. If the nearest `emailos.toml` or `emailos.json` sets `local_storage = true`, they are saved under that config folder's `.email/sent/` directory instead. Each file contains:
* Email subject as heading
* Sender and recipient information
* Date sent
* Full email body content
## Integration with Other Commands
The sent command works well with other EmailOS commands:
```bash
# Search for specific sent emails first
mailos sent --subject "invoice" --days 30
# Open a specific sent email in your mail app
mailos open --id [email_id]
```
## Tips
* Use the `--json` flag for programmatic access to sent email data
* Combine filters for more precise results: `mailos sent --to client@company.com --days 14`
* The `--days` filter is often more practical than specific date ranges
* Markdown files are automatically organized by date for easy reference
* Use the account flag when managing multiple email accounts
## Troubleshooting
### Common Issues
**"No sent emails found"**
* Check if your email provider uses a different sent folder name
* Verify you have sent emails in the specified time period
* Try without filters to see if any sent emails are accessible
**"Authentication failed"**
* Ensure your email configuration is correct
* Verify your app-specific password is valid
* Try the `mailos auth` command to re-authenticate
**"Failed to connect to IMAP server"**
* Check your internet connection
* Verify IMAP settings for your email provider
* Some providers require specific IMAP configurations
For additional help, see the main EmailOS documentation or use `mailos help sent`.
---
---
url: /delete.md
---
# EmailOS Delete Command Documentation
The `mailos delete` command permanently removes emails or drafts from your email account.
## Basic Usage
```bash
mailos delete [flags]
```
Deletes emails based on specified criteria. **Requires confirmation flag for safety.**
## Command-Line Flags
### Basic Options
| Flag | Short | Type | Default | Description | Example |
|------|-------|------|---------|-------------|---------|
| `--account` | | string | | Email account to use | `mailos delete --account value` |
| `--days` | | int | 0 | Delete emails older than N days | `mailos delete --days value` |
| `--from` | | string | | Delete all from sender | `mailos delete --from value` |
| `--subject` | | string | | Delete all with subject | `mailos delete --subject value` |
### Advanced Options
| Flag | Short | Type | Default | Description | Example |
|------|-------|------|---------|-------------|---------|
| `--after` | | string | | Delete emails after date (YYYY-MM-DD) | `mailos delete --after value` |
| `--before` | | string | | Delete emails before date (YYYY-MM-DD) | `mailos delete --before value` |
| `--confirm` | | bool | false | Confirm deletion | `mailos delete --confirm` |
| `--drafts` | | bool | false | Delete drafts instead of regular emails | `mailos delete --drafts` |
| `--ids` | | uintslice | | Email IDs to delete | `mailos delete --ids value` |
## Safety Features
### Confirmation Required
All delete operations require the `--confirm` flag to prevent accidental deletions:
```bash
# This will fail with an error
mailos delete --from spam@example.com
# This will work
mailos delete --from spam@example.com --confirm
```
### Preview Before Deletion
The command shows what will be deleted before proceeding:
```bash
mailos delete --from spam@example.com --confirm
# Output:
# Found 15 email(s) to delete:
# - [Jan 2] From: spam@example.com - Special Offer!
# - [Jan 3] From: spam@example.com - Limited Time Deal
# ... and 13 more
# ✓ Deleted 15 email(s)
```
## Examples
### Delete specific emails by ID
```bash
# Get email IDs first
mailos search --from unwanted@example.com
# Delete specific emails
mailos delete --ids 123,456,789 --confirm
```
### Delete all emails from a sender
```bash
mailos delete --from marketing@company.com --confirm
```
### Delete emails by subject
```bash
mailos delete --subject "Unsubscribe" --confirm
```
### Delete old emails
```bash
# Delete emails older than 90 days
mailos delete --days 90 --confirm
# Delete emails before specific date
mailos delete --before 2024-01-01 --confirm
```
### Delete drafts
```bash
# Delete all drafts
mailos delete --drafts --confirm
# Delete drafts from specific sender
mailos delete --drafts --from old@example.com --confirm
```
### Combine filters
```bash
# Delete old emails from specific sender
mailos delete --from newsletter@example.com --days 30 --confirm
# Delete emails in date range
mailos delete --after 2024-01-01 --before 2024-06-01 --confirm
```
## Output Information
The delete command provides detailed feedback:
```bash
mailos delete --from spam@example.com --confirm
# Output:
# Reading emails to delete...
# Found 8 email(s) to delete:
# - [Dec 15] From: spam@example.com - You've Won!
# - [Dec 16] From: spam@example.com - Claim Your Prize
# - [Dec 17] From: spam@example.com - Final Notice
# ... and 5 more
# ✓ Deleted 8 email(s)
```
## Getting Email IDs
Use the search command to find email IDs before deletion:
```bash
# Search for emails to get IDs
mailos search --from unwanted@example.com
mailos search --subject "promotion"
mailos search --days 30
```
## Error Handling
Common errors and solutions:
```bash
# Missing confirmation
Error: please use --confirm flag to delete emails
# Solution: Add --confirm flag
# Invalid date format
Error: invalid --before date format (use YYYY-MM-DD)
# Solution: Use YYYY-MM-DD format: 2024-01-01
# No emails found
No emails found matching criteria
# This is normal - no action needed
```
## Safety Best Practices
1. **Always test first**: Use `mailos search` with the same criteria to see what would be deleted
2. **Start small**: Delete a few emails first, then scale up
3. **Use specific filters**: Combine multiple flags to target exactly what you want to delete
4. **Backup important emails**: Export critical emails before bulk deletion
### Test Before Delete Workflow
```bash
# 1. Test the search criteria first
mailos search --from marketing@company.com --days 30
# 2. Review the results, then delete with same criteria
mailos delete --from marketing@company.com --days 30 --confirm
```
## Folder Support
* **Inbox**: Default target for email deletion
* **Drafts**: Use `--drafts` flag to target draft folder
* **Gmail**: Automatically handles Gmail's special folder structure
## Notes
* Deletions are permanent and cannot be undone
* Large bulk deletions may take several minutes
* The command processes up to 1000 emails per operation
* Deleted emails are moved to trash/deleted items folder (behavior depends on email provider)
* Some email providers may have additional retention policies
## Troubleshooting
### Authentication errors
1. Check your email configuration: `mailos setup`
2. Verify your email password/app password is correct
3. Ensure IMAP access is enabled for your email provider
### Connection issues
1. Verify internet connection
2. Check if your email provider's IMAP server is accessible
3. Try again later if server is temporarily unavailable
### Permission errors
1. Ensure your email account has delete permissions
2. Some corporate accounts may restrict deletion
3. Contact your email administrator if needed
## See Also
* [`mailos search`](search.md) - Find emails before deletion
* [`mailos read`](read.md) - Read specific emails before deciding to delete
* [`mailos drafts`](drafts.md) - Manage draft emails
---
---
url: /download.md
---
# EmailOS Download Command Documentation
The `mailos download` command downloads email attachments from your inbox based on search criteria and saves them to a specified directory.
## Basic Usage
```bash
mailos download [flags]
```
Downloads attachments from emails that match your search criteria to a local directory, perfect for organizing project files and client communications.
## Command-Line Flags
| Flag | Description | Default | Example |
|------|-------------|---------|---------|
| `--account` | Email account to use | | `mailos download --account work@company.com` |
| `--id` | Download attachments from specific email ID | | `mailos download --id 12345` |
| `--from` | Filter by sender email address | | `mailos download --from "client@company.com"` |
| `--to` | Filter by recipient email address | | `mailos download --to "legal@company.com"` |
| `--subject` | Filter by subject line (partial match) | | `mailos download --subject "contract"` |
| `--days` | Search emails from last N days (0 = no limit, max: 365) | 0 | `mailos download --days 30` |
| `--number` | Maximum number of emails to search (max: 1000) | 10 | `mailos download --number 50` |
| `--output-dir` | Directory to save attachments | `./attachments` | `mailos download --output-dir ./project-docs` |
| `--show-content` | Show email content preview with attachment details | false | `mailos download --show-content` |
## Project-Based Workflows
The download command is designed for organizing emails and attachments by project or topic:
### Scenario 1: Download Client Project Files
```bash
# Navigate to your project directory
cd /path/to/client-project
# Download all attachments from specific client
mailos download --from "client@company.com" --output-dir ./attachments
# Download contract-related files from last 30 days
mailos download --subject "contract" --days 30 --output-dir ./contracts
```
### Scenario 2: Legal Document Organization
```bash
# Create organized structure
mkdir -p legal-docs/contracts legal-docs/agreements
# Download different types of legal documents
mailos download --from "legal@company.com" --subject "contract" --output-dir ./legal-docs/contracts
mailos download --from "legal@company.com" --subject "agreement" --output-dir ./legal-docs/agreements
```
### Scenario 3: Specific Email Thread
```bash
# Download attachments from a specific email discussion
mailos download --id 12345 --output-dir . --show-content
```
## Examples
### Download all attachments from a specific sender
```bash
mailos download --from "john@example.com" --number 20 --output-dir ./john-files
```
### Download recent attachments with subject filter
```bash
mailos download --subject "proposal" --days 7 --output-dir ./proposals
```
### Download from multiple criteria
```bash
mailos download --from "vendor@company.com" --subject "invoice" --days 90 --output-dir ./invoices
```
### Download with content preview
```bash
mailos download --from "team@company.com" --show-content --number 5
```
## Getting Email IDs
Before downloading from a specific email ID, use the search command to find the ID:
```bash
# Search for emails to get IDs
mailos search --from "client@company.com"
mailos search --subject "important document"
mailos search --days 7
```
The search results will show email IDs that you can use with the `--id` flag.
## Output and Organization
### Attachment Handling
* Attachments are saved with their original filenames
* Duplicate filenames are automatically handled with timestamps
* Directory structure is created automatically if it doesn't exist
* Empty directories are created even if no attachments are found
### Progress Indicators
* Shows total number of emails found
* Displays attachment count per email
* Indicates final save location
* Provides warnings for large operations
### Performance and Limits
* Maximum 1000 emails per search (prevents system overload)
* Maximum 365 days for date range searches
* 2-minute timeout for single email operations
* 5-minute timeout for batch search operations
## Error Handling
### Common Issues and Solutions
**Email ID not found:**
```
Error: email with ID 12345 not found
```
* Verify the email ID using `mailos search`
* Check if the email has been deleted or moved
**Operation timeout:**
```
Error: operation timed out after 5 minutes
```
* Reduce search scope with `--number` or `--days`
* Check network connection
* Try searching for a more specific criteria
**No attachments found:**
```
No emails with attachments found matching criteria
```
* Broaden search criteria (remove filters)
* Check if emails actually have attachments
* Verify account access and authentication
## Security and Privacy
* Attachments are downloaded to your local system only
* No data is transmitted to external services
* Respects existing email account authentication
* Works with all supported email providers (Gmail, FastMail, Outlook, etc.)
## Integration with Other Commands
### Workflow Integration
```bash
# Find emails first
mailos search --from "client@company.com" --days 30
# Read specific email for context
mailos read 12345
# Download its attachments
mailos download --id 12345 --output-dir ./client-files
# Send response
mailos send --to "client@company.com" --subject "Re: Documents received"
```
### Batch Operations
```bash
# Download from multiple sources to organized structure
mailos download --from "legal@company.com" --output-dir ./legal
mailos download --from "finance@company.com" --output-dir ./finance
mailos download --from "hr@company.com" --output-dir ./hr
```
## Tips and Best Practices
1. **Use specific output directories** for better organization
2. **Combine filters** (--from, --subject, --days) for precise results
3. **Use --show-content** to preview before bulk downloads
4. **Start with small --number values** to test your filters
5. **Create project-specific directories** before downloading
6. **Use --days parameter** to limit scope and improve performance
## Troubleshooting
### Permission Issues
Ensure you have write permissions to the output directory:
```bash
chmod 755 ./attachments
```
### Large Volume Downloads
For large attachment downloads:
* Use smaller --number values (10-50)
* Filter by specific date ranges (--days)
* Download in batches by sender or subject
### Network Issues
If experiencing timeouts:
* Check internet connection
* Reduce search scope
* Try downloading specific emails by ID first
---
---
url: /open.md
---
# Open Command
Open specific emails in your system's default mail application using email ID, sender, subject, or other criteria. Works cross-platform with macOS Mail, Outlook, Thunderbird, and other mail clients.
## Usage
```bash
mailos open [flags]
```
## Description
The `open` command allows you to quickly open emails in your default mail application. You can specify emails by their ID, sender, subject line, or choose from the most recent emails. The command integrates with your system's default mail client to provide a seamless email management experience.
## Flags
### Identification Flags
* `--id ` - Email ID to open
* `--message-id ` - Open email directly by Message-ID
* `--from ` - Open email from specific sender
* `--subject ` - Open email by subject (partial match)
* `--last ` - Open from last N emails (opens most recent)
### Account Management
* `--account ` - Email account to use (if different from default)
## Examples
### Open by Email ID
```bash
# Open email with specific ID
mailos open --id 123
# Open email by Message-ID
mailos open --message-id ""
```
### Open by Sender
```bash
# Open most recent email from specific sender
mailos open --from sender@example.com
```
### Open by Subject
```bash
# Open most recent email with subject containing "Meeting"
mailos open --subject "Meeting"
# Open email with partial subject match
mailos open --subject "Invoice"
```
### Open Recent Emails
```bash
# Open from last 5 emails (opens most recent)
mailos open --last 5
# Open the most recent email
mailos open --last 1
```
### Multi-Account Usage
```bash
# Open email using specific account
mailos open --id 123 --account work@company.com
```
## Platform Support
### macOS
* Integrates with Mail.app using AppleScript
* Searches by subject and sender for accurate email matching
* Falls back to search interface if direct email access fails
### Windows
* Supports Outlook with search functionality
* Uses mailto: URLs for fallback compatibility
* Works with default mail client configuration
### Linux
* Compatible with Thunderbird and other mail clients
* Uses xdg-open for system integration
* Supports standard mail client protocols
## How It Works
1. **Authentication**: Ensures you're authenticated with the email provider
2. **Email Search**: If no ID specified, searches for emails matching criteria
3. **Mail Client Integration**: Opens the email in your default mail application
4. **Cross-Platform**: Uses platform-specific methods to integrate with mail clients
## Search Behavior
When using search criteria (--from, --subject, --last):
* Searches through your inbox first
* Falls back to sent folder if not found in inbox
* Returns most recent match when multiple emails match
* Uses fuzzy matching for subject and sender fields
## Error Handling
The command handles common scenarios:
* Email not found: Returns helpful error message
* Mail client not available: Provides fallback options
* Authentication issues: Prompts for re-authentication
* Invalid email ID: Returns clear error message
## Notes
* The command requires an active internet connection for IMAP access
* Some mail clients may require additional permissions for automation
* Search results are limited to recent emails for performance
* The --last flag opens the most recent email from the specified range
## Related Commands
* [`mailos search`](search.md) - Advanced email search with filtering
* [`mailos read`](read.md) - Read email content in terminal
* [`mailos sent`](sent.md) - View sent emails
## Troubleshooting
### Mail Client Not Opening
* Ensure your default mail client is properly configured
* Try opening the mail client manually first
* Check system permissions for mail client automation
### Email Not Found
* Verify the email ID is correct
* Try using search criteria instead of ID
* Check if the email is in a different folder
### Authentication Issues
* Run `mailos config` to verify account settings
* Ensure app-specific passwords are current
* Check internet connection and IMAP settings
---
---
url: /save.md
---
# Save Command
Save emails to file in multiple formats including EML, plain text, and JSON.
## Overview
The `save` command allows you to export emails from your mailbox to local files. EML format is the default and preserves the complete email structure, making it viewable in any email client. Text and JSON formats are also available for different use cases.
## Usage
```bash
# Single email mode
mailos save [flags]
# Thread download mode
mailos save --thread-for [flags]
# Batch mode (search criteria)
mailos save --from [flags]
mailos save --subject [flags]
```
## Basic Examples
### Save email as EML (default)
```bash
# Save email to current directory
mailos save 1234 --account user@example.com
# Save to specific directory
mailos save 1234 --account user@example.com --output-dir ~/emails
# Save and open in mail client
mailos save 1234 --account user@example.com --open
```
### Save in different formats
```bash
# Save as plain text
mailos save 1234 --account user@example.com --format txt
# Save as JSON
mailos save 1234 --account user@example.com --format json
# Save without headers
mailos save 1234 --account user@example.com --include-headers=false
```
## Advanced Usage
### Custom filename and organization
```bash
# Custom file prefix
mailos save 1234 --account user@example.com --file-prefix "archived_"
# Organized by date in specific directory
mailos save 1234 --account user@example.com \
--output-dir ~/email-archive/$(date +%Y-%m) \
--file-prefix "work_"
```
### Batch saving workflow
```bash
# Find emails and save them
mailos search --account user@example.com --from important@client.com --days 7 --json | \
jq -r '.[].id' | \
while read email_id; do
mailos save "$email_id" --account user@example.com --output-dir ~/important-emails
done
```
## Thread Download Functionality
The save command supports downloading complete email threads involving specific email addresses or aliases. This is useful for archiving conversations, backing up important communications, or analyzing email patterns.
### Save emails for specific alias or address
```bash
# Download all emails FROM and TO a specific alias
mailos save --account user@example.com --thread-for user@company.com --format eml --output-dir ./thread-backup
# Download all threads for the current account
mailos save --account user@example.com --all-threads --output-dir ./all-threads --days 90
# Download threads with specific date range and format
mailos save --account user@example.com --thread-for client@external.com --days 365 --format json --output-dir ./client-archive
```
### Thread download features
* **Alias Support**: Works with email aliases and cross-domain addresses
* **Deduplication**: Automatically removes duplicate emails based on Message-ID
* **Thread Summary**: Generates markdown summary with participant analysis and email timeline
* **Filtering**: Only includes emails that actually contain the specified address in TO/FROM/CC/BCC fields
* **Multiple Formats**: Supports EML, TXT, and JSON output formats
### Thread summary generation
When using thread download, a `thread_summary.md` file is automatically created containing:
* Total email count and participant statistics
* Email timeline with previews
* Attachment information
* Thread conversation analysis
### Thread download examples
```bash
# Archive all communications with a specific client
mailos save --account work@company.com --thread-for client@example.com --output-dir ./client-archive --days 365
# Backup alias-based communications
mailos save --account [PERSONAL_ACCOUNT] --thread-for [ALIAS_ADDRESS] --format eml --output-dir ./alias-backup
# Download recent threads for compliance
mailos save --account [LEGAL_ACCOUNT] --all-threads --days 30 --format json --output-dir ./compliance-archive
```
## Batch Operations
### Save multiple emails by criteria
```bash
# Save emails from specific sender (last 30 days)
mailos save --account user@example.com --from [VENDOR_ADDRESS] --format eml --output-dir ./vendor-emails
# Save emails by subject pattern
mailos save --account user@example.com --subject "invoice" --days 30 --format json --output-dir ./invoices
# Save only attachments from specific sender
mailos save --account user@example.com --from client@example.com --attachments-only --output-dir ./client-attachments
```
## Output Formats
### EML Format (default)
* **Use case**: Viewing in email clients, archiving, forwarding
* **Features**: Preserves all email structure, headers, attachments
* **Extension**: `.eml`
* **Compatibility**: Works with Mail.app, Outlook, Thunderbird, etc.
### Text Format
* **Use case**: Reading content, text processing, simple archiving
* **Features**: Headers + plain text body only
* **Extension**: `.txt`
* **Content**: From, To, Subject, Date, and body text
### JSON Format
* **Use case**: Data processing, integration with other tools
* **Features**: Complete structured email data
* **Extension**: `.json`
* **Content**: All email fields as JSON object
## Filename Convention
Saved files use this naming pattern:
```
[prefix][timestamp]_[subject].ext
```
Examples:
* `email_20241201_143022_Meeting_Notes.eml`
* `archived_20241201_143022_Invoice_12345.txt`
* `backup_20241201_143022_Project_Update.json`
## Integration Examples
### Save emails from search results
```bash
# Save all emails from specific sender
mailos search --account user@example.com --from [VENDOR_ADDRESS] --json | \
jq -r '.[].id' | head -10 | \
xargs -I {} mailos save {} --account user@example.com --output-dir ~/vendor-emails
# Save important emails by subject
mailos search --account user@example.com --subject "invoice" --days 30 --json | \
jq -r '.[].id' | \
xargs -I {} mailos save {} --account user@example.com --format json --output-dir ~/invoices
```
### Archive workflow
```bash
#!/bin/bash
# Archive old emails script
ACCOUNT="user@example.com"
ARCHIVE_DIR="$HOME/email-archive/$(date +%Y)"
# Create archive directory
mkdir -p "$ARCHIVE_DIR"
# Find emails older than 6 months and archive them
mailos search --account "$ACCOUNT" --older-than-days 180 --limit 100 --json | \
jq -r '.[].id' | \
while read email_id; do
echo "Archiving email $email_id..."
mailos save "$email_id" --account "$ACCOUNT" \
--output-dir "$ARCHIVE_DIR" \
--file-prefix "archived_" \
--format eml
done
```
## Error Handling
### Common issues and solutions:
**Email not found**
```bash
mailos save 99999 --account user@example.com
# Error: email with ID 99999 not found
```
Solution: Verify email ID with `mailos search` first.
**Permission denied**
```bash
mailos save 1234 --account user@example.com --output-dir /root/emails
# Error: failed to create output directory: permission denied
```
Solution: Use a writable directory or run with appropriate permissions.
**Disk space**
```bash
# Check available space before saving
df -h ~/email-archive
mailos save 1234 --account user@test.com --output-dir ~/email-archive
```
## Security Considerations
### File permissions
Saved emails contain sensitive information:
```bash
# Save with restricted permissions
umask 077 # Only owner can read
mailos save 1234 --account user@example.com --output-dir ~/private-emails
```
### Cleanup
```bash
# Clean up temporary files after viewing
mailos save 1234 --account user@example.com --open --cleanup-temp
```
## Related Commands
* [`mailos read`](read.md) - Read emails in the terminal
* [`mailos search`](search.md) - Find emails to save
* [`mailos download`](download.md) - Download email attachments
## Tips and Best Practices
1. **Use EML for long-term archiving** - Most compatible format
2. **Organize by date** - Use `--output-dir` with date-based paths
3. **Verify before bulk operations** - Test save commands with single emails first
4. **Check disk space** - Email archives can grow large quickly
5. **Use descriptive prefixes** - Help organize different types of saved emails
## Command Reference
Save an email to a file in EML, text, or JSON format. EML format is the default and preserves full email structure for viewing in email clients.
### Usage
```bash
# Single email mode
mailos save [flags]
# Thread download mode
mailos save --thread-for [flags]
# Batch mode (search criteria)
mailos save --from [flags]
mailos save --subject [flags]
```
### Flags
#### Basic Save Options
| Flag | Short | Type | Default | Description |
|------|-------|------|---------|-------------|
| `--account` | `-a` | string | | Email account to use |
| `--cleanup-temp` | | bool | `true` | Clean up temporary files after opening |
| `--dry-run` | | bool | `false` | Preview what would be done without actually doing it |
| `--file-prefix` | | string | `"email_"` | Prefix for saved email filename |
| `--format` | | string | `"eml"` | Output format: eml, txt, json (default: eml) |
| `--include-headers` | | bool | `true` | Include email headers in output |
| `--open` | | bool | `false` | Open saved email in default mail client |
| `--output-dir` | | string | | Output directory for saved email (default: current directory) |
#### Thread and Batch Operations
| Flag | Short | Type | Default | Description |
|------|-------|------|---------|-------------|
| `--all-threads` | | bool | `false` | Download all email threads for the specified account |
| `--attachments-only` | | bool | `false` | Save only attachments, not email content |
| `--days` | | int | `0` | Search emails from last N days (0 = no limit, max: 365) |
| `--from` | | string | | Filter emails by sender address |
| `--limit` | | int | `10` | Maximum number of emails to search (default: 10, max: 1000) |
| `--show-content` | | bool | `false` | Show email content preview with details |
| `--subject` | | string | | Filter emails by subject line (partial match) |
| `--thread-for` | | string | | Download all email threads involving this email address |
| `--to` | | string | | Filter emails by recipient address |
### Arguments
* `` - The unique ID of the email to save
### Examples
#### Single Email Save
```bash
# Save email as EML to current directory
mailos save 1234 --account user@example.com
# Save as JSON to specific directory
mailos save 1234 --account user@example.com --format json --output-dir ~/exports
# Save and open in mail client
mailos save 1234 --account user@example.com --open
# Save with custom prefix and no headers
mailos save 1234 --account user@example.com --file-prefix "backup_" --include-headers=false
```
#### Thread Download Examples
```bash
# Download all emails for a specific alias
mailos save --account [WORK_ACCOUNT] --thread-for [ALIAS_ADDRESS] --output-dir ~/alias-archive
# Download all account threads from last 30 days
mailos save --account user@example.com --all-threads --days 30 --format eml --output-dir ~/monthly-backup
# Download specific sender's thread as JSON
mailos save --account user@example.com --thread-for client@example.com --format json --output-dir ~/client-comms
```
#### Batch Operations
```bash
# Save all emails from specific sender (last 7 days)
mailos save --account user@example.com --from [VENDOR_ADDRESS] --days 7 --output-dir ~/vendor
# Save only attachments from client emails
mailos save --account user@example.com --from client@example.com --attachments-only --output-dir ~/attachments
```
---
---
url: /echo.md
---
# EmailOS Echo Command Documentation
The `mailos echo` command sends a message to the email address MailOS resolves for the current directory. It is a self-send shortcut built on the same delivery path and flags as `mailos send`.
## Basic Usage
```bash
mailos echo --subject "Test" --body "Checking MailOS delivery"
```
Use `--dry-run` to preview the resolved sender and recipient without sending:
```bash
mailos echo --subject "Test" --body "Checking MailOS delivery" --dry-run
```
## Recipient Resolution
`mailos echo` fills `--to` automatically. It resolves the recipient in this order:
1. `MAILOS_FROM_EMAIL`
2. `MAILOS_EMAIL_ADDRESS`
3. The nearest parent `emailos.json` or `emailos.toml` `from_address` or `email_address`
4. The default MailOS account in the user's machine config, such as `~/.email/config.json`
When `mailos echo` falls back to the default machine config, it also uses that account for sending.
## Relationship to Send
`mailos echo` reuses the normal `mailos send` flags and delivery behavior. You can use send options such as:
```bash
mailos echo --subject "Plain test" --body "Hello" --plain
mailos echo --subject "File test" --file message.md
mailos echo --subject "Preview" --body "Hello" --dry-run
```
`mailos echo` is intentionally for self-sends. If you need to send to another address, use `mailos send --to recipient@example.com`.
## Useful Checks
Inspect the resolved project send identity:
```bash
mailos whoami
mailos env
```
Confirm the message in the sent folder:
```bash
mailos sent --number 5 --days 1 --save-markdown=false
```
---
---
url: /natural_language.md
---
# Natural Language Command
The `nl` (natural language) command allows you to query and manage your emails using natural language instead of traditional command-line flags and options.
## Overview
This command uses Ollama to parse natural language queries into structured email operations. You can express email commands in plain English and the system will automatically convert them to the appropriate technical operations.
## Prerequisites
* Ollama must be installed and running locally (default: http://localhost:11434)
* At least one language model must be installed in Ollama
* EmailOS must be configured with valid email credentials
## Usage
```bash
mailos nl "natural language query"
```
## Examples
### Search Operations
```bash
# Find emails from a specific person
mailos nl "show all emails from John this month"
# Search by subject
mailos nl "find emails about invoices"
# Search unread messages
mailos nl "list unread messages from clients today"
# Search with attachments
mailos nl "show emails with attachments from last week"
# Complex searches
mailos nl "find urgent emails from my manager about project updates"
```
### Email Management
```bash
# Count emails
mailos nl "how many emails from support this week"
# Summarize content
mailos nl "summarize important emails from yesterday"
# Read specific emails
mailos nl "read email with id 12345"
```
## Flags
* `--account EMAIL`: Specify which email account to use
* `--verbose`: Show detailed parsing information and debug output
* `--dry-run`: Preview what would be executed without actually running the command
* `--model MODEL`: Specify which Ollama model to use for parsing
* `--ollama-url URL`: Ollama server URL (default: http://localhost:11434)
* `--list-models`: List available Ollama models and exit
* `--check-ollama`: Check Ollama connection and available models
## Supported Actions
The natural language parser can handle these types of operations:
* **list/show/search**: Find and display emails
* **read**: Read specific email content
* **count**: Count matching emails
* **summarize**: Generate summaries of email content
## Supported Filters
You can use natural language to specify:
* **From/To**: "emails from John", "messages to the team"
* **Subject**: "about meetings", "regarding invoices"
* **Date ranges**: "today", "this week", "last month", "since Monday"
* **Status**: "unread messages", "important emails"
* **Attachments**: "with attachments", "containing files"
## Model Recommendations
### For Speed
* `llama3.2:3b` - Fast parsing, good for simple queries
* `phi3:mini` - Very fast, minimal resource usage
### For Accuracy
* `llama3.1:8b` - Better understanding of complex queries
* `llama3.2:7b` - Good balance of speed and accuracy
## Setup and Configuration
### Install Ollama
```bash
# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh
# Start Ollama service
ollama serve
# Install a recommended model
ollama pull llama3.2:3b
```
### Check Installation
```bash
# Verify Ollama is running and check models
mailos nl --check-ollama
# List available models
mailos nl --list-models
```
## Examples with Flags
```bash
# Use specific model
mailos nl "find emails from client@example.com" --model llama3.1:8b
# Preview command without executing
mailos nl "delete all spam emails" --dry-run
# Verbose parsing information
mailos nl "show recent invoices" --verbose
# Use specific account
mailos nl "list unread messages" --account work@company.com
```
## Troubleshooting
### Ollama Not Found
```
Error: Cannot connect to Ollama server at http://localhost:11434
```
* Ensure Ollama is installed: `curl -fsSL https://ollama.ai/install.sh | sh`
* Start Ollama: `ollama serve`
* Check if running: `ollama list`
### No Models Available
```
Error: No models available in Ollama
```
* Install a model: `ollama pull llama3.2:3b`
* List available models: `ollama list`
### Parsing Errors
```
Error: No valid JSON found in model response
```
* Try a different model: `--model llama3.1:8b`
* Rephrase your query more clearly
* Use simpler language and specific terms
### Slow Performance
```
Error: Ollama request timed out
```
* Use a smaller/faster model: `ollama pull phi3:mini`
* Increase timeout or use simpler queries
* Check system resources
## Advanced Usage
### Predefined Filters
The system recognizes common email patterns:
* `clients` → emails from client domains
* `invoices` → emails about billing/payments
* `meetings` → emails about meetings/calls
* `urgent` → important/priority emails
* `unread` → unread messages only
* `today` → emails from today
* `attachments` → emails with file attachments
### Custom Ollama Server
```bash
# Use remote Ollama instance
mailos nl "find emails" --ollama-url http://remote-server:11434
# Use custom model
mailos nl "search messages" --model custom-model:latest
```
## Integration with Other Commands
The natural language command generates standard mailos commands, so you can:
1. Use `--dry-run` to see the equivalent command
2. Run the suggested command directly
3. Combine with other mailos features
```bash
# See equivalent command
mailos nl "find emails from John" --dry-run
# Output: Would execute: ./mailos search --from John -n 10
# Run the equivalent directly
mailos search --from John -n 10
```
## Security and Privacy
* Natural language queries are processed locally by Ollama
* No data is sent to external services
* All email content remains on your local system
* Ollama models run entirely offline
## Performance Tips
1. Use smaller models for faster parsing: `phi3:mini`, `llama3.2:3b`
2. Be specific in your queries to reduce ambiguity
3. Use predefined filters when possible
4. Consider using traditional commands for complex operations
## See Also
* [Search Command](search.md) - Traditional email search
* [Read Command](read.md) - Reading specific emails
* [Setup Guide](setup.md) - Initial configuration
* [Installation](installation.md) - Installing EmailOS
---
---
url: /prompts.md
---
# Prompts Command Documentation
## Overview
The `prompts` command allows users to access and manage user prompts that can be used with AI email drafting and management. Prompts provide standardized templates for different types of email interactions and help maintain consistency in AI-assisted email composition.
## Usage
```bash
mailos prompts [prompt-name] [flags]
```
## Flags
* `--account string` - Email account to use
* `-i, --interactive` - Force interactive mode (default behavior, kept for compatibility)
* `--list` - Show static list of available prompts (non-interactive)
## Features
### Prompt Management
* Interactive prompt selection with user-friendly interface
* List all available prompts with descriptions
* Copy prompts directly to clipboard for easy use
* Access embedded user prompts from the `user-prompts/` directory
### Prompt Selection
* Interactive selection menu with descriptions
* Direct access by prompt name
* List view for browsing available prompts
* Automatic clipboard integration for immediate use
### Clipboard Integration
* Automatically copies selected prompts to clipboard
* Works with system clipboard for easy pasting
* Provides user feedback when content is copied
## Examples
### List all available prompts
```bash
mailos prompts --list
```
### Interactive prompt selection
```bash
mailos prompts
# or
mailos prompts --interactive
```
### Get specific prompt by name
```bash
mailos prompts email-drafting
```
### Use with specific account
```bash
mailos prompts --account work@company.com
```
## Prompt Structure
User prompts are stored as Markdown files in the `user-prompts/` directory and contain:
* Descriptive content for the prompt
* Instructions for AI assistants
* Context-specific guidelines
* Best practices for email composition
## Integration
The prompts system integrates with:
* AI email drafting functionality
* Email management commands
* Interactive email composition
* Multi-account email management
## Available Prompts
Prompts are automatically discovered from the embedded `user-prompts/` directory. Each `.md` file represents a separate prompt that can be accessed by its filename (without extension).
The system provides user-friendly descriptions by reading the first non-header line from each prompt file, making it easy to understand what each prompt is designed for.
---
---
url: /templates.md
---
# EmailOS Template Command Documentation
The `mailos template` command manages HTML email templates for styling outgoing emails with custom designs and branding.
**For Developers**: This command also serves as a reference implementation for the EmailOS CLI core command patterns. See `internal/core/TEMPLATE.go` for both traditional and modern BaseCommand implementation examples.
## Basic Usage
```bash
mailos template
```
Opens interactive template editor to customize your email appearance.
## Quick Start
### View Existing Template
```bash
mailos template --open-browser
```
Opens your current template HTML file directly in the browser for quick visual inspection.
### Edit Template Interactively
```bash
mailos template
```
Opens the full interactive template editor with design options.
## Command-Line Flags
| Flag | Description | Example |
|------|-------------|---------|
| `--remove` | Remove existing template | `mailos template --remove` |
| `--open-browser` | Open template HTML file in browser | `mailos template --open-browser` |
## Template Features
### Supported Elements
* Custom colors and fonts
* Logo/branding placement
* Header and footer sections
* Signature formatting
* Button styles
* Responsive design
* Dark mode support
### Template Variables
Templates can use placeholders:
* `{{BODY}}` - Email content
* `{{SIGNATURE}}` - Email signature
* `{{DATE}}` - Current date
* `{{FROM_NAME}}` - Sender name
* `{{FROM_EMAIL}}` - Sender email
* `{{PROFILE_IMAGE}}` - Profile picture
## Interactive Editor
Running `mailos template` launches the editor with options:
### 1. Quick Styles
Pre-designed templates:
* **Professional** - Clean business style
* **Modern** - Contemporary design
* **Minimal** - Simple and elegant
* **Creative** - Colorful and bold
* **Dark** - Dark theme
* **Custom** - Build from scratch
### 2. Customization Options
#### Colors
* Primary color (headers, links)
* Secondary color (accents)
* Background color
* Text color
* Border color
#### Typography
* Font family selection
* Font size adjustments
* Line height settings
* Heading styles
#### Layout
* Container width
* Padding/margins
* Border radius
* Shadow effects
#### Branding
* Logo upload/URL
* Logo position
* Company name
* Tagline
## Template Examples
### Professional Template
```html
{{FROM_NAME}}
{{BODY}}
```
### Minimal Template
```html
{{FROM_NAME}}
{{BODY}}
{{SIGNATURE}}
```
## Template Management
### Save Location
Templates are stored in:
* Global: `~/.email/templates/default.html`
* Local: `./.email/templates/default.html`
### View Template in Browser
```bash
mailos template --open-browser
```
Instantly opens your current template HTML file in the default browser for visual review. This is useful for:
* Quick visual inspection of template design
* Testing template appearance without sending emails
* Debugging layout issues
* Reviewing HTML structure and styling
The command automatically locates your template file and opens it using the system's default browser. If no template exists, it will show an error message.
### Apply Template
Templates are automatically applied to:
* Emails sent with `mailos send`
* Unless `--plain` flag is used
* When body contains markdown
### Remove Template
```bash
mailos template --remove
```
Reverts to plain email format.
### Export Template
```bash
cp ~/.email/template.html my-template.html
```
### Import Template
```bash
cp my-template.html ~/.email/template.html
```
## Advanced Customization
### CSS Framework Integration
Use popular frameworks:
```html
```
### Responsive Design
```css
@media only screen and (max-width: 600px) {
.email-container {
width: 100% !important;
}
.content {
padding: 10px !important;
}
}
```
### Dark Mode Support
```css
@media (prefers-color-scheme: dark) {
.email-container {
background: #1a1a1a;
color: #ffffff;
}
}
```
### Custom Fonts
```html
```
## Profile Images
### Adding Profile Image
```bash
mailos configure --profile-image /path/to/image.jpg
```
### Using in Template
```html
```
### Image Hosting
Options for profile images:
1. Base64 encoded (embedded)
2. URL to hosted image
3. Gravatar integration
4. Local file reference
## Template Best Practices
### 1. Email Client Compatibility
* Use inline CSS
* Avoid JavaScript
* Test in multiple clients
* Use table layouts for complex designs
### 2. Accessibility
* Include alt text for images
* Use semantic HTML
* Ensure color contrast
* Test with screen readers
### 3. Performance
* Optimize images
* Minimize CSS
* Avoid external dependencies
* Keep file size under 100KB
### 4. Mobile Optimization
* Single column layout
* Large tap targets
* Readable font sizes
* Responsive images
## Testing Templates
### Browser Preview
```bash
mailos template --open-browser
```
Opens template HTML file directly in browser for immediate visual inspection.
### Email Preview
```bash
mailos send --to your@email.com --subject "Template Test" --body "Test content" --preview
```
Shows complete email content with template applied before sending.
### Test Across Clients
Test in:
* Gmail
* Outlook
* Apple Mail
* Mobile apps
* Web clients
### Validation
Check for:
* HTML validity
* CSS compatibility
* Image loading
* Link functionality
## Common Patterns
### Call-to-Action Button
```html
Click Here
```
### Social Media Links
```html
```
## Troubleshooting
### Template Not Applied
* Check template file exists
* Verify not using `--plain` flag
* Ensure HTML is valid
* Check for syntax errors
### Images Not Showing
* Use absolute URLs
* Check image permissions
* Verify HTTPS for external images
* Consider base64 encoding
### Styling Issues
* Use inline CSS
* Avoid modern CSS features
* Test in target email clients
* Check specificity conflicts
### Template Too Large
* Optimize images
* Minimize CSS
* Remove unused styles
* Consider simpler design
## Examples
### Corporate Template
```bash
mailos template
# Select "Professional"
# Set company colors
# Add logo URL
# Customize fonts
```
### Personal Blog Template
```bash
mailos template
# Select "Creative"
# Choose vibrant colors
# Add profile image
# Custom signature
```
### Newsletter Template
```bash
mailos template
# Select "Modern"
# Wide layout
# Header image
# Social media links
```
## Tips
1. **Start Simple**: Begin with minimal template and add features
2. **Test Often**: Send test emails after each major change
3. **Keep Backups**: Save working templates before modifications
4. **Use Variables**: Leverage placeholders for dynamic content
5. **Mobile First**: Design for mobile, enhance for desktop
---
---
url: /template.md
---
# EmailOS Template Command Documentation
The `mailos template` command manages HTML email templates for styling outgoing emails with custom designs and branding.
## Basic Usage
```bash
mailos template
```
Opens interactive template management interface with options to create, edit, preview, or list templates.
## Command-Line Flags
### Basic Options
| Flag | Short | Type | Default | Description | Example |
|------|-------|------|---------|-------------|---------|
| `--account` | | string | | Email account to use | `mailos template --account value` |
| `--content` | | string | | HTML content for template | `mailos template --content value` |
| `--from` | | string | | Email account to use (alias for --account) | `mailos template --from value` |
### Advanced Options
| Flag | Short | Type | Default | Description | Example |
|------|-------|------|---------|-------------|---------|
| `--copy` | | string | | Copy from existing template name | `mailos template --copy value` |
| `--edit` | | bool | false | Open template in default HTML editor | `mailos template --edit` |
| `--file` | | string | | Read HTML content from file | `mailos template --file value` |
| `--image` | | string | | Local image file to embed as base64 | `mailos template --image value` |
| `--name` | | string | | Template name | `mailos template --name value` |
| `--open-browser` | | bool | false | Open template HTML file in browser | `mailos template --open-browser` |
| `--remove` | | bool | false | Remove existing template | `mailos template --remove` |
| `--template-dir` | | string | | Set template directory for account | `mailos template --template-dir value` |
## Interactive Template Management
Running `mailos template` without flags opens an interactive menu with three options:
### 1. Create/Edit Template
* Prompts for template name if not provided with `--name`
* Multi-line HTML input terminated by typing "END" on a new line
* Validates that template contains `{{BODY}}` placeholder
* Optional preview before saving
* Saves to appropriate location (local or global)
### 2. Preview Existing Template
* Lists available templates if no name specified
* Loads template and opens preview in browser with sample content
* Replaces placeholders with preview data for visual testing
### 3. List Templates
* Shows all available templates from both local and global locations
* Displays template names and their file paths
## Template System
### Placeholder Variables
Templates support the following placeholders that are replaced when emails are sent:
* `{{BODY}}` - Email content (required)
* `{{PROFILE_IMAGE}}` - Profile picture (optional)
### Storage Locations
Templates are stored with priority order:
1. **Local project**: `.email/templates/[name].html`
2. **Global user**: `~/.email/templates/[name].html`
Local templates take precedence over global ones with the same name.
### Template Files
* Saved as HTML files with `.html` extension
* Named templates: `[name].html`
* Default template: `default.html`
## Quick Actions
### View Template in Browser
```bash
mailos template --open-browser
```
Opens your current default template HTML file directly in the browser for visual inspection. Useful for:
* Quick visual review of template design
* Testing template appearance without sending emails
* Debugging layout issues
### Create Named Template
```bash
mailos template --name company
```
Creates or edits a template with the specified name.
### Remove Template
```bash
mailos template --remove --name company
```
Removes the specified template. If no name provided, removes "default" template.
## Template Structure
### Basic Template Example
```html
{{PROFILE_IMAGE}}
My Company
{{BODY}}
```
### Professional Template Example
```html
Professional Email
{{BODY}}
```
### Minimal Template Example
```html
{{PROFILE_IMAGE}}
Company Name
{{BODY}}
Best regards,
Your Name
```
## Profile Images
### Profile Image Handling
When `{{PROFILE_IMAGE}}` placeholder is used:
* Images are base64-encoded and embedded directly in the email
* Supported formats: JPG, JPEG, PNG, GIF, WEBP
* Automatically styled with `max-width: 150px; border-radius: 50%;`
* If no profile image is configured, placeholder is removed
### Profile Image Tag Output
The system generates HTML like:
```html
```
## Integration with Email System
### Automatic Template Application
Templates are automatically applied when:
* Sending emails with `mailos send` command
* Email body contains markdown or HTML content
* Template file exists for the specified name (default: "default")
### Template Bypass
Templates are bypassed when:
* Using `--plain` flag with send commands
* No template file exists
* Template loading fails
## Template Management Commands
### List All Templates
```bash
mailos template
# Choose option 3: List templates
```
Shows all available templates with their file paths.
### Preview Template
```bash
mailos template
# Choose option 2: Preview existing template
```
Opens template in browser with sample content for visual testing.
### Edit Existing Template
```bash
mailos template --name existing-template
# Choose option 1: Create/Edit template
```
Loads existing template for modification or creates new one if it doesn't exist.
## Best Practices
### Email Client Compatibility
* Use inline CSS for maximum compatibility
* Avoid JavaScript (not supported by most email clients)
* Test with multiple email clients (Gmail, Outlook, Apple Mail)
* Use table layouts for complex designs if needed
### Performance and Size
* Keep total email size under 100KB
* Optimize images before base64 encoding
* Minimize CSS to reduce file size
* Avoid external dependencies
### Accessibility
* Include alt text for images
* Use semantic HTML structure
* Ensure sufficient color contrast
* Test with screen readers
### Mobile Optimization
* Use responsive design principles
* Test on mobile devices
* Ensure readable font sizes
* Make tap targets large enough
## Troubleshooting
### Template Not Applied
* Verify template file exists at expected location
* Check that template contains `{{BODY}}` placeholder
* Ensure not using `--plain` flag when sending
* Validate HTML syntax
### Images Not Showing
* Check that profile image file exists and is readable
* Verify image format is supported (JPG, PNG, GIF, WEBP)
* Ensure image file size is reasonable (under 1MB recommended)
### Browser Preview Issues
* Check that default browser is configured
* Verify template file permissions
* Test opening file manually in browser
### Template Saving Issues
* Ensure directory permissions allow file creation
* Check available disk space
* Verify file path is valid and accessible
## Examples
### Creating Company Template
```bash
mailos template --name company
# Paste your company HTML template
# Type "END" when finished
# Preview if desired
# Confirm save
```
### Quick Browser Preview
```bash
mailos template --open-browser
```
### Remove Old Template
```bash
mailos template --remove --name old-template
```
### List Available Templates
```bash
mailos template
# Choose option 3
```
## File Locations
Templates are stored in these locations based on your configuration:
* **Local Project**: `.email/templates/[name].html` (if `.email` directory exists)
* **Global User**: `~/.email/templates/[name].html` (default location)
The system automatically creates the necessary directories when saving templates.
---
---
url: /scheduled-sending.md
---
# EmailOS Scheduled Email Sending
Send emails at a future time using EmailOS's built-in scheduler. Schedule emails with simple commands and let the watch daemon handle sending them at the right time.
## Quick Start
```bash
# Schedule an email for 2 hours from now
mailos send --to user@example.com \
--subject "Meeting Reminder" \
--body "Don't forget our 3pm meeting" \
--schedule-in 2h
# Start the scheduler to send scheduled emails
mailos watch
```
## How It Works
1. **Schedule emails** using `--schedule-at` or `--schedule-in` flags with the `send` command
2. **Start the scheduler** with `mailos watch` in a dedicated terminal or background process
3. **Emails are sent automatically** at their scheduled time
4. **Sent emails are archived** to `~/.email/sent-scheduled/`
## Scheduling Commands
### Schedule Using Relative Time (`--schedule-in`)
Schedule emails relative to the current time using Go duration format:
```bash
# 30 minutes from now
mailos send --to client@example.com \
--subject "Follow-up" \
--body "Checking in on the proposal" \
--schedule-in 30m
# 2 hours from now
mailos send --to team@company.com \
--subject "Daily Update" \
--body "Here's today's progress report" \
--schedule-in 2h
# 24 hours (tomorrow at this time)
mailos send --to boss@company.com \
--subject "Weekly Report" \
--body "This week's accomplishments..." \
--schedule-in 24h
# 1 hour 30 minutes from now
mailos send --to vendor@example.com \
--subject "Contract Review" \
--body "Please review the attached contract" \
--schedule-in 1h30m
```
#### Supported Duration Units
* `s` - seconds (e.g., `30s`)
* `m` - minutes (e.g., `15m`)
* `h` - hours (e.g., `2h`)
* Combinations (e.g., `1h30m`, `2h15m30s`)
### Schedule Using Absolute Time (`--schedule-at`)
Schedule emails for a specific date and time using RFC3339 format:
```bash
# Specific date and time (UTC)
mailos send --to user@example.com \
--subject "Quarterly Review" \
--body "Q4 results are ready for review" \
--schedule-at "2026-01-28T09:00:00Z"
# Specific date and time (with timezone)
mailos send --to client@example.com \
--subject "Project Launch" \
--body "The new feature goes live today!" \
--schedule-at "2026-02-01T15:00:00-05:00"
# ISO8601 format (without timezone assumes local time)
mailos send --to team@company.com \
--subject "Meeting Reminder" \
--body "Stand-up meeting in 1 hour" \
--schedule-at "2026-01-28T10:30:00"
```
#### Time Format Requirements
* RFC3339: `2006-01-02T15:04:05Z` (UTC)
* RFC3339 with timezone: `2006-01-02T15:04:05-07:00`
* ISO8601: `2006-01-02T15:04:05` (local time)
**Note:** Scheduled time must be in the future. Past times will result in an error.
## Managing Scheduled Emails
### List Scheduled Emails
View all pending scheduled emails:
```bash
mailos schedule-list
```
Example output:
```
📬 Scheduled Emails (3)
1. ⏰ Pending
ID: 1769539111027403000
To: [client@example.com]
Subject: Follow-up Meeting
Scheduled: 2026-01-28 14:30:00 (in 2h 15m)
Created: 2026-01-28 12:15:00
2. ⏰ Pending
ID: 1769539212027403001
To: [team@company.com]
Subject: Daily Update
Scheduled: 2026-01-28 17:00:00 (in 4h 45m)
Created: 2026-01-28 12:15:00
3. ⚡ Due now
ID: 1769539313027403002
To: [boss@company.com]
Subject: Urgent Report
Scheduled: 2026-01-28 12:00:00
Created: 2026-01-28 11:55:00
💡 Run 'mailos watch' to start the scheduler
```
### Watch Command - The Scheduler Daemon
The `watch` command monitors scheduled emails and sends them at the right time:
```bash
# Start watching with default 1-minute interval
mailos watch
# Check every 30 seconds (more responsive)
mailos watch --interval 30s
# Check every 5 minutes (lower resource usage)
mailos watch --interval 5m
# Show detailed output (useful for debugging)
mailos watch --verbose
# Process due emails once and exit (useful for cron jobs)
mailos watch --once
```
#### Watch Command 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: Follow-up Meeting → [client@example.com]
```
### Watch Command Flags
| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--interval` | duration | 1m0s | Check interval (e.g., 30s, 1m, 5m) |
| `--once` | bool | false | Process due emails once and exit |
| `--verbose` | bool | false | Show detailed output including SMTP debug info |
## Storage Locations
Scheduled emails are stored in JSON format in your home directory:
* **Pending emails**: `~/.email/scheduled-emails/`
* **Sent archive**: `~/.email/sent-scheduled/`
### File Format
Each scheduled email is stored as a JSON file:
```
~/.email/scheduled-emails/20260128_143000_1769539111027403000.json
```
Filename format: `{scheduled_time}_{email_id}.json`
## Workflow Examples
### Simple Daily Reminder
Schedule a daily reminder at 9 AM:
```bash
# Calculate time until 9 AM tomorrow
mailos send --to yourself@example.com \
--subject "Daily Task Reminder" \
--body "Don't forget to review the project board" \
--schedule-at "2026-01-29T09:00:00Z"
```
### Batch Scheduling
Schedule multiple emails at once:
```bash
# Morning follow-up
mailos send --to client1@example.com \
--subject "Project Update" \
--body "..." \
--schedule-in 2h
# Afternoon check-in
mailos send --to client2@example.com \
--subject "Status Check" \
--body "..." \
--schedule-in 6h
# Evening summary
mailos send --to team@company.com \
--subject "Daily Summary" \
--body "..." \
--schedule-in 10h
# Start the scheduler
mailos watch
```
### Background Scheduler
Run the scheduler as a background process:
```bash
# Using nohup (output to log file)
nohup mailos watch --interval 30s > ~/mailos-scheduler.log 2>&1 &
# Using disown (bash/zsh)
mailos watch --interval 30s &
disown
# Check if scheduler is running
ps aux | grep "mailos watch"
# Stop the scheduler
pkill -f "mailos watch"
```
### Cron Integration
Use `watch --once` in a cron job for scheduled checks:
```bash
# Add to crontab: crontab -e
# Check every 5 minutes
*/5 * * * * /usr/local/bin/mailos watch --once >> ~/mailos-cron.log 2>&1
# Check every hour at :00
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 Terminal Launch
Add to your shell startup file (`~/.zshrc` or `~/.bashrc`):
```bash
# Start scheduler silently in background on terminal launch
if ! pgrep -f "mailos watch" > /dev/null; then
nohup mailos watch --interval 30s > /dev/null 2>&1 &
fi
```
## Advanced Usage
### Scheduling with All Send Features
Combine scheduling with other send command features:
```bash
# Schedule email with attachments
mailos send --to client@example.com \
--subject "Proposal Document" \
--body "Please review the attached proposal" \
--attach ~/Documents/proposal.pdf \
--schedule-in 3h
# Schedule with CC and BCC
mailos send --to lead@example.com \
--cc manager@company.com \
--bcc compliance@company.com \
--subject "Contract Agreement" \
--body "Please review and sign" \
--schedule-at "2026-01-29T10:00:00Z"
# Schedule with custom signature
mailos send --to vendor@example.com \
--subject "Purchase Order" \
--body "Attached is the PO for review" \
--signature "Best regards,\nProcurement Team" \
--schedule-in 24h
# Schedule markdown email with template
mailos send --to newsletter@company.com \
--subject "Monthly Newsletter" \
--file newsletter.md \
--template \
--schedule-at "2026-02-01T08:00:00Z"
```
### Account-Specific Scheduling
Schedule emails from specific accounts:
```bash
# From work account
mailos send --account work@company.com \
--to client@example.com \
--subject "Work Update" \
--body "..." \
--schedule-in 2h
# From personal account
mailos send --account personal@gmail.com \
--to friend@example.com \
--subject "Catch up" \
--body "..." \
--schedule-at "2026-01-29T18:00:00Z"
```
## Troubleshooting
### Email Not Sent at Scheduled Time
**Problem**: Email remains in scheduled queue past its scheduled time.
**Solution**:
1. Check if `mailos watch` is running: `ps aux | grep "mailos watch"`
2. Verify no errors in watch output: `mailos watch --verbose`
3. Check system time is correct: `date`
4. Manually process due emails: `mailos watch --once`
### Watch Command Not Finding Due Emails
**Problem**: Watch command reports "No emails due" when emails should be sent.
**Solution**:
1. List scheduled emails: `mailos schedule-list`
2. Verify scheduled time is in the past
3. Check file permissions: `ls -la ~/.email/scheduled-emails/`
4. Run watch with verbose flag: `mailos watch --once --verbose`
### Cannot Schedule Past Times
**Problem**: Error: "scheduled time must be in the future"
**Solution**:
* Verify your system time is correct: `date`
* For `--schedule-at`, ensure timezone is specified correctly
* For `--schedule-in`, use positive durations only
### Scheduler High Resource Usage
**Problem**: Watch command using too much CPU or memory.
**Solution**:
* Increase check interval: `mailos watch --interval 5m` (instead of default 1m)
* Use cron with `--once` instead of continuous watch
* Check for orphaned watch processes: `pkill -f "mailos watch"`
### Email Sent But Still in Queue
**Problem**: Email was sent but still appears in `mailos schedule-list`.
**Solution**:
* Check sent-scheduled folder: `ls ~/.email/sent-scheduled/`
* Manually remove from queue: `rm ~/.email/scheduled-emails/{email_file}.json`
* Restart watch command
## Integration Examples
### With Email Groups
Schedule bulk emails to groups:
```bash
# Schedule to email group
mailos send --group team-leads \
--subject "Leadership Meeting" \
--body "Agenda attached" \
--schedule-at "2026-01-29T14:00:00Z"
```
### With Natural Language
Combine with natural language parsing:
```bash
# Natural language will be parsed, then scheduled
mailos send "remind the team about tomorrow's meeting" --schedule-in 12h
```
### Preview Before Scheduling
Preview the email before scheduling:
```bash
# Preview the email (won't schedule)
mailos send --to user@example.com \
--subject "Test" \
--body "Preview content" \
--preview
# Then schedule if satisfied
mailos send --to user@example.com \
--subject "Test" \
--body "Preview content" \
--schedule-in 1h
```
## Best Practices
1. **Keep watch running**: Use background process or cron for reliable sending
2. **Use relative times** for near-future emails (easier than calculating exact times)
3. **Use absolute times** for emails that must go at specific times (e.g., 9 AM daily)
4. **Check scheduler logs**: Use `--verbose` to debug timing issues
5. **Set appropriate intervals**: 1 minute for time-sensitive, 5 minutes for general use
6. **Monitor sent folder**: Review `~/.email/sent-scheduled/` periodically
7. **Test with short durations**: Use `--schedule-in 1m` to test your setup
8. **Archive old scheduled emails**: Clean up `~/.email/sent-scheduled/` monthly
## Related Commands
* [`mailos send`](send.md) - Main email sending command with all flags
* `mailos schedule-list` - List all scheduled emails
* `mailos watch` - Scheduler daemon to send scheduled emails
## Files and Directories
| Path | Purpose |
|------|---------|
| `~/.email/scheduled-emails/` | Pending scheduled emails (JSON format) |
| `~/.email/sent-scheduled/` | Archive of sent scheduled emails |
| `~/.email/.email/config.json` | Account configuration used by scheduler |
## Technical Details
### Email Message Structure
Each scheduled email is stored with complete metadata:
```json
{
"id": "1769539111027403000",
"scheduled_at": "2026-01-28T14:30:00Z",
"message": {
"to": ["client@example.com"],
"cc": [],
"bcc": [],
"subject": "Follow-up Meeting",
"body": "Let's discuss the project status",
"attachments": [],
"include_signature": true
},
"account_email": "andrew@email-os.com",
"created_at": "2026-01-28T12:15:00Z"
}
```
### Scheduling Algorithm
1. Email is saved to `~/.email/scheduled-emails/` with timestamp in filename
2. Watch command checks directory every interval (default: 1 minute)
3. Compares `scheduled_at` time with current time
4. Sends email if `scheduled_at <= current_time`
5. Moves sent email to `~/.email/sent-scheduled/`
6. Removes from scheduled queue
### Time Precision
* Check interval determines precision (default: 1 minute)
* Emails sent within 1 minute of scheduled time (or your custom interval)
* For more precise timing, use shorter intervals: `--interval 10s`
## See Also
* [Send Command Documentation](send.md) - Complete send command reference
* [Draft Management](drafts.md) - Managing email drafts
* [Configuration](configure.md) - Setting up accounts
---
---
url: /scheduled.md
---
# Scheduled Command
The scheduled email system stores queued emails and sends them when due.
Use these commands:
```bash
mailos schedule-list
mailos watch
```
`schedule-list` shows queued emails and `watch` continuously processes due emails.
---
---
url: /watch.md
---
# EmailOS Watch Command Documentation
The `mailos watch` command monitors scheduled emails and automatically sends them at their scheduled time.
## Quick Start
```bash
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:
```bash
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 → [team@company.com]
```
### Custom Check Interval
Check more frequently for time-sensitive emails:
```bash
mailos watch --interval 30s
```
Or check less frequently to save resources:
```bash
mailos watch --interval 5m
```
### One-Time Processing
Process all due emails once and exit (useful for cron jobs):
```bash
mailos watch --once
```
### Verbose Mode
See detailed SMTP debugging information:
```bash
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:
```bash
nohup mailos watch --interval 30s > ~/mailos-scheduler.log 2>&1 &
```
Check if running:
```bash
ps aux | grep "mailos watch"
```
Stop the scheduler:
```bash
pkill -f "mailos watch"
```
### Using screen or tmux
Run in a persistent terminal session:
```bash
# 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`:
```ini
[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:
```bash
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:
```bash
# 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
Labelcom.emailos.watchProgramArguments/usr/local/bin/mailoswatch--interval1mRunAtLoadKeepAliveStandardOutPath/tmp/mailos-watch.logStandardErrorPath/tmp/mailos-watch-error.log
```
Load the service:
```bash
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`:
```bash
# 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:
```bash
# 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`](send.md#scheduling) - Schedule emails for future sending
* [`mailos schedule-list`](scheduled-sending.md#list-scheduled-emails) - List all scheduled emails
* [Scheduled Sending Guide](scheduled-sending.md) - 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
---
---
url: /sync.md
---
# 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
```
## Related Commands
* `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.
---
---
url: /plugins.md
---
# Plugins Command
## Overview
The `plugins` command lists email-related plugins and tools required for EmailOS functionality. It shows installation status of email sync tools (isync/mbsync), mail transfer agents (msmtp), search engines (notmuch, mu), and other platform-specific email utilities.
## Usage
```bash
mailos plugins [flags]
```
## Flags
* `--all`: Show all plugins including optional ones
* `--required`: Show only required plugins
* `--missing`: Show only missing/uninstalled plugins
* `--check-paths`: Check actual installation paths (default: true)
* `--install-guide`: Show installation guides for missing plugins
* `--json`: Output as JSON
* `--verbose`: Show detailed output and debugging information
## Examples
```bash
# Show required plugins and status
mailos plugins
# Show all available plugins
mailos plugins --all
# Show only missing plugins
mailos plugins --missing
# Output as JSON
mailos plugins --json
# Show installation instructions
mailos plugins --install-guide
```
## Platform-Specific Plugins
### macOS
* **isync (mbsync)**: IMAP synchronization tool for email download
* **msmtp**: SMTP client for sending emails
* **notmuch**: Fast email search and indexing
* **mu (mailutils)**: Alternative fast email search engine (optional)
* **curl**: HTTP client for web requests
* **CA Certificates**: SSL/TLS certificate bundle
### Linux
* **isync (mbsync)**: IMAP synchronization tool
* **msmtp**: SMTP client
* **notmuch**: Fast email search and indexing
* **mu4e**: Alternative email search (optional)
* **curl**: HTTP client
* **CA Certificates**: SSL/TLS certificates
### Windows
* **Git Bash**: Unix-like command line environment
* **WSL**: Windows Subsystem for Linux (recommended)
* **isync/msmtp/notmuch**: Available via WSL
* **Outlook Integration**: Native Windows email client integration (optional)
## Installation
Most plugins can be installed using your system's package manager:
### macOS (Homebrew)
```bash
brew install isync msmtp notmuch mu ca-certificates
```
### Linux (Ubuntu/Debian)
```bash
sudo apt-get install isync msmtp notmuch mu4e curl ca-certificates
```
### Windows
```bash
# Install WSL first
wsl --install
# Then install tools in WSL
wsl sudo apt install isync msmtp notmuch
```
## Quick Install
Use the EmailOS install script to install all dependencies:
```bash
curl -fsSL https://email-os.com/install | bash
```
Or use the built-in installer:
```bash
mailos plugins --missing --install-guide
```
---
---
url: /accounts.md
---
# EmailOS Accounts Command Documentation
The `mailos accounts` command manages multiple email accounts, aliases, and sub-emails for use across your email workflow.
## Basic Usage
```bash
mailos accounts [flags]
```
## Command-Line Flags
### Advanced Options
| Flag | Short | Type | Default | Description | Example |
|------|-------|------|---------|-------------|---------|
| `--clear` | | bool | false | Clear session default account | `mailos accounts --clear` |
| `--list` | | bool | false | List all available accounts (default behavior) | `mailos accounts --list` |
| `--set` | | string | | Set session default account | `mailos accounts --set value` |
## Account Types and Organization
EmailOS automatically organizes your accounts into three categories:
### Primary Accounts (🏠)
The main account for each email provider, used for authentication.
### Sub-emails (↳)
Additional email addresses that use the same provider credentials as a primary account. These include:
* Email aliases configured at your provider
* Additional addresses from the same domain
* Forwarding addresses that share authentication
### Secondary Accounts
Completely separate accounts from different email providers.
## Managing Aliases and Sub-Emails
### Adding Aliases Manually
**Important**: EmailOS does not automatically sync aliases from email providers. You must add them manually.
To add an alias or sub-email:
```bash
mailos accounts --set alias@example.com
```
When you specify an email that doesn't exist locally, EmailOS will:
1. Detect it's not configured
2. Prompt: "Account 'alias@example.com' not found. Would you like to add this account? (y/N):"
3. If you answer "y", guide you through the setup process
### Provider-Specific Setup
#### Fastmail
```bash
# Add your Fastmail alias
mailos accounts --set alias@example.com
# Use the same app password as your main Fastmail account
# EmailOS will automatically label it as "Sub-email"
```
#### Gmail
```bash
# Add your Gmail alias (configured in Gmail Settings > Accounts)
mailos accounts --set alias@example.com
# Use the same app password as your main Gmail account
```
#### Microsoft/Office 365
```bash
# Add your Office 365 alias
mailos accounts --set alias@company.com
# Use the same credentials as your main Office 365 account
```
### Alias Syncing Limitations
**No Automatic Discovery**: EmailOS cannot automatically detect aliases from email providers because:
* Most providers don't expose alias information via IMAP/POP3
* API access varies significantly between providers
* Security policies often restrict alias enumeration
**Manual Configuration Required**: You must add each alias individually using the `mailos accounts --set` command.
**Same Provider = Same Credentials**: When adding an alias from the same provider as an existing account, use the same authentication credentials (app password, etc.).
## Account Workflow Examples
### Example 1: Adding a Fastmail Alias
```bash
# You have: john@example.com (primary Fastmail account)
# You want: support@example.com (Fastmail alias)
mailos accounts --set support@example.com
# Prompts to add account -> Yes
# Provider detected: fastmail
# Enter app password: [same as john@example.com]
# Result: support@example.com added as "Sub-email"
```
### Example 2: Listing All Accounts
```bash
mailos accounts --list
```
Output:
```
Available Accounts:
==================
Fastmail:
🏠 john@example.com (Primary)
↳ support@example.com (Sub-email)
Gmail:
🏠 user@example.com (Primary)
```
### Example 3: Setting Session Default
```bash
# Set default account for current session
mailos accounts --set support@example.com
# Now all commands use support@example.com unless overridden
mailos send --to customer@company.com --subject "Support Response"
```
### Example 4: Using Specific Account for Sending
```bash
# Send from specific account regardless of default
mailos send --from support@example.com --to customer@company.com --subject "Help"
```
## Configuration Storage
### Global Configuration
* **Location**: `~/.email/config.json`
* **Scope**: Available across all projects and directories
* **Contains**: All account credentials and settings
### Local Configuration
* **Location**: `./.email/config.json` (in current directory)
* **Scope**: Project-specific overrides
* **Contains**: Local account preferences and defaults
### Configuration Inheritance
Local configurations inherit missing settings from global configuration, allowing project-specific account preferences while maintaining global credentials.
## Troubleshooting
### "Account not found" Error
```bash
mailos send --from alias@example.com --to recipient@example.com --subject "Test"
# Error: account 'alias@example.com' not found. Available accounts: [list]
```
**Solution**: Add the alias using `mailos accounts --set alias@example.com`
### "Authentication failed" for Sub-email
**Problem**: Using different credentials for an alias from the same provider.
**Solution**: Use the same app password/credentials as the primary account from that provider.
### Sub-email Not Labeled Correctly
**Problem**: Alias appears as separate account instead of sub-email.
**Solution**: Ensure you're using the exact same provider credentials. EmailOS automatically detects same-provider accounts and labels them as sub-emails.
### Cannot Send from Alias
**Problem**: Email sends from primary account instead of alias.
**Solution**:
1. Verify alias is added: `mailos accounts --list`
2. Use explicit `--from` flag: `mailos send --from alias@example.com`
3. Check that your email provider supports sending from that alias
## Best Practices
1. **Add aliases as soon as you configure them at your provider**
2. **Use the same credentials for all accounts from the same provider**
3. **Test sending from aliases before using them in production**
4. **Keep a list of your provider-configured aliases for reference**
5. **Use descriptive local defaults for different projects**
## Related Commands
* `mailos configure` - Initial account setup and configuration
* `mailos send --from ` - Send from specific account
* `mailos help configure` - Detailed configuration documentation
* `mailos help send` - Email sending documentation
## Integration with Other Commands
All EmailOS commands support the `--account` flag to specify which account to use:
```bash
mailos sync --account alias@example.com
mailos read --account alias@example.com
mailos search --account alias@example.com
```
For commands that don't specify an account, EmailOS uses this priority order:
1. Local directory default (`.email/config.json`)
2. Session default (set with `mailos accounts --set`)
3. Global default account
4. First available account
---
---
url: /query.md
---
# EmailOS Advanced Query Documentation
EmailOS provides powerful query capabilities for searching, filtering, and analyzing emails using natural language and advanced parameters.
## Query Syntax
### Natural Language Queries
```bash
mailos q="unread emails from john about the project"
mailos "find all emails with attachments from last week"
```
### Direct Query
```bash
# Quoted query (recommended for complex queries)
mailos "emails from CEO sent yesterday"
# Using q= parameter
mailos q="urgent emails with attachments"
```
## Query Parameters
### Basic Filters
| Parameter | Description | Example |
|-----------|-------------|---------|
| `from` | Filter by sender email | `from=john@example.com` |
| `to` | Filter by recipient | `to=me@example.com` |
| `subject` | Filter by subject text | `subject=invoice` |
| `limit`, `n` | Number of results | `limit=50` |
| `days` | Emails from last N days | `days=7` |
| `range` | Time range preset | `range="Last week"` |
### Boolean Filters
| Parameter | Description | Example |
|-----------|-------------|---------|
| `unread` | Only unread emails | `unread=true` |
| `sent` | Only sent emails | `sent=true` |
| `received` | Only received emails | `received=true` |
| `attachments` | Has attachments | `attachments=true` |
### Size Filters
| Parameter | Description | Example |
|-----------|-------------|---------|
| `min-size` | Minimum email size | `min-size=100KB` |
| `max-size` | Maximum email size | `max-size=10MB` |
Size formats supported:
* Bytes: `1000`, `1000b`
* Kilobytes: `10KB`, `10k`
* Megabytes: `5MB`, `5m`
* Gigabytes: `1GB`, `1g`
### Domain Filters
| Parameter | Description | Example |
|-----------|-------------|---------|
| `domains` | Include specific domains | `domains=gmail.com,yahoo.com` |
| `exclude-domains` | Exclude domains | `exclude-domains=spam.com` |
### Content Filters
| Parameter | Description | Example |
|-----------|-------------|---------|
| `keywords` | Must contain keywords | `keywords=urgent,important` |
| `exclude-words` | Must not contain words | `exclude-words=unsubscribe,spam` |
### Aggregation Options
| Parameter | Description | Example |
|-----------|-------------|---------|
| `group-by` | Group results by field | `group-by=sender` |
| `sort-by` | Sort results | `sort-by=date` |
| `top-n` | Limit to top N results | `top-n=10` |
| `format` | Output format | `format=json` |
## Time Range Presets
Use with `range=` parameter:
* `"Last hour"` - Past 60 minutes
* `"Today"` - Since midnight
* `"Yesterday"` - Previous day
* `"This week"` - Current week
* `"Last week"` - Previous week
* `"This month"` - Current month
* `"Last month"` - Previous month
* `"This year"` - Current year
## Complex Query Examples
### 1. Find large attachments from specific sender
```bash
mailos q="from=john@company.com attachments=true min-size=5MB days=30"
```
### 2. Urgent unread emails excluding spam
```bash
mailos "keywords=urgent,asap unread=true exclude-domains=marketing.com,spam.com"
```
### 3. Weekly report from manager
```bash
mailos q="from=manager@company.com subject=report range='This week'"
```
### 4. Cleanup old large emails
```bash
mailos "days=90 min-size=10MB sort-by=size"
```
### 5. Find meeting invites
```bash
mailos q="keywords=meeting,calendar,invite days=7 group-by=sender"
```
### 6. Customer emails with attachments
```bash
mailos "domains=customer.com,client.com attachments=true days=14"
```
### 7. Exclude newsletters and marketing
```bash
mailos q="exclude-words=unsubscribe,newsletter,promotional days=1"
```
### 8. Project-specific emails
```bash
mailos "subject=ProjectX keywords=deadline,milestone from=team.com"
```
## Natural Language Processing
EmailOS understands various natural language patterns:
### Temporal Queries
* "emails from yesterday"
* "messages received last week"
* "mail from the past 3 days"
* "today's unread emails"
### Sender Queries
* "emails from John"
* "messages from @gmail.com"
* "mail from the marketing team"
### Content Queries
* "emails about the project"
* "messages with attachments"
* "urgent emails"
* "unread newsletters"
### Combined Queries
* "unread emails from John about the meeting"
* "large attachments from last month"
* "urgent messages from the CEO today"
## Query Operators
### Logical Operators (in natural language)
* **AND**: "emails from John AND with attachments"
* **OR**: "emails from John OR Jane"
* **NOT**: "emails NOT from marketing"
### Comparison Operators
* Size: `min-size`, `max-size`
* Date: `days`, `range`
* Count: `limit`, `top-n`
## Output Formats
### Default Format
Human-readable text with formatting:
```
📧 Email #12345 (2024-01-15 10:30 AM)
From: john@example.com
Subject: Project Update
Preview: Here's the latest status...
```
### JSON Format
Machine-readable JSON:
```bash
mailos q="from=john@example.com format=json"
```
Output:
```json
[
{
"id": 12345,
"from": "john@example.com",
"subject": "Project Update",
"date": "2024-01-15T10:30:00Z",
"body": "...",
"attachments": []
}
]
```
### CSV Format (future)
```bash
mailos q="format=csv" > emails.csv
```
## Grouping and Aggregation
### Group by Sender
```bash
mailos q="days=30 group-by=sender top-n=10"
```
Shows top 10 senders in the last 30 days.
### Group by Domain
```bash
mailos q="group-by=domain days=7"
```
Shows email distribution by domain.
### Group by Date
```bash
mailos q="group-by=date range='This month'"
```
Shows daily email counts for the current month.
## Sorting Options
### Sort by Date (default)
```bash
mailos q="sort-by=date" # or just sort=date
```
### Sort by Size
```bash
mailos q="attachments=true sort-by=size"
```
### Sort by Sender
```bash
mailos q="sort-by=sender days=7"
```
## Performance Optimization
### Use Specific Filters
More specific queries run faster:
```bash
# Slow
mailos q="emails"
# Fast
mailos q="from=john@example.com days=7 unread=true"
```
### Limit Results
Always use limit for large datasets:
```bash
mailos q="attachments=true limit=100"
```
### Use Time Ranges
Recent emails are cached and faster:
```bash
mailos q="range='Today' unread=true"
```
## Query Chaining
Combine EmailOS commands for powerful workflows:
```bash
# Find and delete old newsletters
mailos q="keywords=newsletter days=30" | \
grep "Email #" | \
cut -d'#' -f2 | \
xargs mailos delete --ids
# Export important emails
mailos q="from=ceo@company.com format=json" > important.json
# Statistics on query results
mailos q="domains=client.com days=30" | mailos stats
```
## Saved Queries
Save frequently used queries in your shell configuration:
```bash
# ~/.bashrc or ~/.zshrc
alias mailos-urgent="mailos q='keywords=urgent,asap unread=true'"
alias mailos-today="mailos q='range=Today sort-by=sender'"
alias mailos-large="mailos q='min-size=5MB days=30'"
```
## Query Tips
1. **Start Broad, Then Narrow**: Begin with simple queries and add filters
2. **Use Quotes**: Always quote complex queries to prevent shell interpretation
3. **Combine Filters**: Multiple filters are AND-ed together
4. **Check Spelling**: Misspelled domains or email addresses return no results
5. **Use Wildcards**: Partial matches work for subject and keywords
6. **Time Ranges**: Use presets for common time periods
7. **Format for Scripts**: Use JSON format when piping to other tools
## Troubleshooting
### No Results
* Check email configuration: `mailos info`
* Verify spelling of email addresses
* Try broader time range
* Remove filters one by one
### Slow Queries
* Add more specific filters
* Use smaller time ranges
* Limit number of results
* Check internet connection for IMAP
### Unexpected Results
* Keywords are case-insensitive
* Domains match subdomains
* Check boolean values (true/false)
* Verify time range
## Advanced Use Cases
### Email Analytics Dashboard
```bash
#!/bin/bash
echo "=== Email Analytics ==="
echo "Today's emails:"
mailos q="range=Today" | wc -l
echo "Unread count:"
mailos q="unread=true" | wc -l
echo "With attachments:"
mailos q="attachments=true days=7" | wc -l
```
### Auto-responder Script
```bash
# Find emails needing response
mailos q="unread=true keywords=request,please days=1 format=json" | \
jq -r '.[] | .from' | \
while read email; do
mailos send --to "$email" --subject "Auto-Reply" \
--body "Thank you for your email. We'll respond within 24 hours."
done
```
### Email Archiver
```bash
# Archive old emails to files
mailos q="days=365 format=json" > archive-$(date +%Y).json
mailos delete days=365 # Optional: delete after archiving
```
## Future Enhancements
Planned query features:
* Regex support for advanced pattern matching
* Full-text search indexing
* Saved query management
* Query history and suggestions
* Machine learning-based smart queries
* Integration with external search engines
---
---
url: /groups.md
---
# EmailOS Groups Command Documentation
The `mailos groups` command manages email groups for bulk email sending. Groups allow you to organize email addresses into named collections that can be used with the `--group` flag in send commands.
## Basic Usage
```bash
# List all groups
mailos groups
# Create a new group
mailos groups --update "team" --emails "user1@example.com,user2@example.com"
# Send email to a group
mailos send --group "team" --subject "Team Update" --body "Hello team!"
```
## Command-Line Flags
### Advanced Options
| Flag | Short | Type | Default | Description | Example |
|------|-------|------|---------|-------------|---------|
| `--account` | `-a` | string | | Email account to use | `mailos groups --account user@example.com` |
| `--add-member` | | string | | Add a member to an existing group | `mailos groups --add-member value` |
| `--delete` | | string | | Delete the specified group | `mailos groups --delete value` |
| `--description` | | string | | Description for the group | `mailos groups --description value` |
| `--emails` | | string | | Comma-separated list of email addresses | `mailos groups --emails value` |
| `--group` | | string | | Group name for add/remove member operations | `mailos groups --group value` |
| `--list-members` | | string | | List all members of the specified group | `mailos groups --list-members value` |
| `--remove-member` | | string | | Remove a member from an existing group | `mailos groups --remove-member value` |
| `--update` | | string | | Create or update a group with the given name | `mailos groups --update value` |
## Group Operations
### Creating Groups
Create a new group with multiple email addresses:
```bash
mailos groups \
--update "dev-team" \
--description "Development team members" \
--emails "alice@company.com,bob@company.com,charlie@company.com"
```
### Listing Groups
View all configured groups:
```bash
mailos groups
```
Output example:
```
Email Groups:
=============
dev-team (3 emails)
Description: Development team members
Emails: alice@company.com, bob@company.com, charlie@company.com
marketing (2 emails)
Description: Marketing team
Emails: marketing1@company.com, marketing2@company.com
```
### Managing Group Members
Add a new member to an existing group:
```bash
mailos groups --add-member "diana@company.com" --group "dev-team"
```
Remove a member from a group:
```bash
mailos groups --remove-member "bob@company.com" --group "dev-team"
```
List all members of a specific group:
```bash
mailos groups --list-members "dev-team"
```
### Updating Groups
Modify an existing group's emails and description:
```bash
mailos groups \
--update "dev-team" \
--description "Updated development team" \
--emails "alice@company.com,charlie@company.com,diana@company.com"
```
Note: Updating a group replaces all existing members with the new list.
### Deleting Groups
Remove a group entirely:
```bash
mailos groups --delete "old-team"
```
## Using Groups with Send Command
Once groups are created, use them with the send command:
### Single Group
```bash
mailos send \
--group "dev-team" \
--subject "Sprint Planning" \
--body "Please join the sprint planning meeting at 2 PM."
```
### Multiple Recipients
Combine groups with individual recipients:
```bash
mailos send \
--group "dev-team" \
--to "manager@company.com" \
--cc "hr@company.com" \
--subject "Project Update" \
--body "Weekly status update attached" \
--attach "status-report.pdf"
```
### Local Recipient Files
`mailos send --group` can also read recipients from a local `.md`, `.markdown`,
or `.txt` file. This is useful when you want a portable recipient set outside
`~/.email/groups.json`. A local file path in `--group` is treated as a recipient
file, not as the message body; keep using `--body`, stdin, or `--file` for the
email content itself.
Recipient files may use YAML-style frontmatter delimiters (`---`) or plain
`key: value` metadata. They must include at least one `to`, `cc`, or `bcc`
recipient.
```text
to: alice@example.com, bob@example.com
cc: manager@example.com
bcc: archive@example.com
name: Team Updates
subject: Project Update
description: Weekly project recipients
preheader: Quick weekly status summary
signature: "Regards, Andrew"
```
```bash
mailos send \
--group ./team-recipients.txt \
--body "Weekly status update attached" \
--dry-run
```
Supported recipient-file metadata fields are:
| Field | Description |
|-------|-------------|
| `to` | Comma-separated primary recipients |
| `cc` | Comma-separated CC recipients |
| `bcc` | Comma-separated BCC recipients |
| `subject` | Default subject when `--subject` is not supplied |
| `name` | Sender display name used for the message |
| `from_name` | Sender display name alias |
| `description` | Human-readable note about the recipient file |
| `preheader` | Preview text for templated messages |
| `signature` | Signature text unless `--no-signature` is used |
| `group` | Group metadata value for frontmatter workflows |
| `priority` | Priority metadata value for frontmatter workflows |
| `file` | Body file metadata used by frontmatter workflows |
Command-line flags still win where applicable. For example, `--subject` overrides
a `subject:` value in the recipient file.
### Nested Recipient Files
Values inside `to`, `cc`, or `bcc` can also reference another local recipient
file in the same directory. Use either an explicit filename such as
`finance.txt` or an extensionless name such as `finance`; extensionless names
are resolved by trying `.txt`, `.md`, and `.markdown`.
The nested file's `to`, `cc`, and `bcc` recipients are flattened into the field
that referenced it. This lets a parent file control whether a reusable nested
group is used as To, CC, or BCC for that send.
Parent file:
```text
to: lead@example.com
cc: project-watchers
bcc: audit-archive
name: Project Updates
```
`project-watchers.txt`:
```text
to: manager@example.com, ops@example.com
```
`audit-archive.txt`:
```text
to: archive@example.com
```
Dry-run the expanded send before removing `--dry-run`:
```bash
mailos send \
--group ./parent.txt \
--subject "Nested group check" \
--body "Checking nested recipient expansion" \
--plain \
--dry-run
```
The preview expands to:
```text
To: lead@example.com
CC: manager@example.com, ops@example.com
BCC: archive@example.com
```
Nested group references are resolved relative to the file that contains the
reference. Recursive references fail with an error instead of looping.
## Group Storage
Groups are stored in `~/.email/groups.json` in JSON format:
```json
{
"groups": [
{
"name": "dev-team",
"description": "Development team members",
"emails": [
"alice@company.com",
"bob@company.com",
"charlie@company.com"
]
}
]
}
```
## Email Validation
When adding emails to groups, EmailOS performs basic validation:
* Emails must contain an "@" symbol
* Invalid emails are automatically filtered out
* Duplicate emails within a group are prevented
* Case-insensitive duplicate detection
## Use Cases
### Team Communications
```bash
# Organize by department
mailos groups --update "engineering" --emails "eng1@company.com,eng2@company.com"
mailos groups --update "design" --emails "designer1@company.com,designer2@company.com"
# Send department updates
mailos send --group "engineering" --subject "Code Review Process" --file code-review.md
```
### Client Management
```bash
# Organize clients by project
mailos groups --update "project-alpha" --emails "client1@example.com,pm@example.com"
# Send project updates
mailos send --group "project-alpha" --subject "Alpha Project Status" --file alpha-update.md
```
## Error Handling
Common errors and solutions:
### Group Not Found
```
Error: group 'team-name' not found
```
* Verify group name spelling
* Use `mailos groups` to list available groups
* Create the group first if it doesn't exist
### Invalid Email Addresses
```
Error: no valid emails provided
```
* Ensure emails contain "@" symbol
* Check for typos in email addresses
* Provide at least one valid email
### Missing Required Flags
```
Error: --group flag is required when adding members
```
* Specify the target group when adding/removing members
* Use `--group "group-name"` flag
## Best Practices
### Group Naming
* Use descriptive, lowercase names with hyphens
* Examples: `dev-team`, `customers-premium`, `project-alpha`
* Avoid spaces and special characters
### Email Management
* Regularly audit group membership
* Remove bounced or inactive email addresses
* Validate new email addresses before adding
* Use consistent email formatting
## Notes
* Group names are case-insensitive for lookups
* Maximum group size is limited by your email provider's recipient limits
* Groups are stored locally and not synced across devices
* Email addresses are normalized to lowercase for consistency
---
---
url: /report.md
---
# EmailOS Report Command Documentation
The `mailos report` command generates comprehensive email reports for specified time ranges with detailed analytics and summaries.
## Basic Usage
```bash
mailos report
```
Interactive time range selector followed by detailed report generation.
## Command-Line Flags
| Flag | Description | Example |
|------|-------------|---------|
| `--range` | Time range for report | `--range "This week"` |
| `--output` | Save report to file | `--output report.md` |
## Time Range Options
### Interactive Selection
When run without `--range` flag, provides menu with:
* Last hour
* Today
* Yesterday
* This week
* Last week
* This month
* Last month
* Last 7 days
* Last 30 days
* This year
* Custom range
### Preset Ranges
Use with `--range` flag:
| Range | Description |
|-------|-------------|
| `"Last hour"` | Previous 60 minutes |
| `"Today"` | Midnight to now |
| `"Yesterday"` | Previous calendar day |
| `"This week"` | Current week (Mon-Sun) |
| `"Last week"` | Previous full week |
| `"This month"` | Current calendar month |
| `"Last month"` | Previous calendar month |
| `"Last 7 days"` | Rolling 7-day window |
| `"Last 30 days"` | Rolling 30-day window |
| `"This year"` | Current calendar year |
## Report Contents
### Summary Section
* Time period covered
* Total emails analyzed
* Daily average
* Peak activity times
### Sender Analysis
* Top 10 most frequent senders
* Email count per sender
* Percentage of total volume
* New vs recurring senders
### Domain Statistics
* Most common email domains
* Corporate vs personal email ratio
* Domain distribution chart
### Time Analysis
* Hourly distribution
* Day of week patterns
* Peak communication times
* Response time estimates
### Subject Analysis
* Common keywords
* Topic clustering
* Thread identification
* Subject line patterns
### Attachment Summary
* Total attachments
* File type distribution
* Size statistics
* Sender attachment patterns
### Communication Patterns
* Conversation threads
* Reply frequencies
* Communication networks
* Key relationships
## Output Formats
### Terminal Display (Default)
Formatted markdown with:
* Headers and sections
* ASCII charts
* Tables
* Color highlighting (if supported)
### File Output
Save to markdown file:
```bash
mailos report --range "This month" --output monthly-report.md
```
Supports:
* Markdown (.md)
* Plain text (.txt)
* HTML (.html) - auto-converted
* PDF (.pdf) - requires pandoc
## Examples
### Weekly Report
```bash
mailos report --range "This week"
```
### Monthly Report to File
```bash
mailos report --range "Last month" --output reports/december-2024.md
```
### Today's Activity
```bash
mailos report --range "Today"
```
### Custom Date Range
```bash
mailos report
# Select "Custom range" from menu
# Enter start date: 2024-12-01
# Enter end date: 2024-12-15
```
### Quarterly Report
```bash
# Last 90 days
mailos report --range "Last 90 days" --output Q4-report.md
```
## Report Sections Detail
### 1. Executive Summary
```
Report Period: Dec 1-31, 2024
Total Emails: 847
Daily Average: 27.3
Busiest Day: Tuesday (156 emails)
Peak Hour: 9:00 AM - 10:00 AM
```
### 2. Sender Breakdown
```
Top Senders:
1. john@company.com (89 emails, 10.5%)
2. notifications@example.com (67 emails, 7.9%)
3. team@example.com (45 emails, 5.3%)
...
```
### 3. Communication Heatmap
```
Hour Mon Tue Wed Thu Fri Sat Sun
00:00 2 1 0 3 1 0 0
01:00 0 0 1 0 0 0 0
...
09:00 15 22 18 20 16 2 1
```
### 4. Thread Analysis
```
Active Threads: 34
Longest Thread: "Project Alpha Discussion" (23 messages)
Most Participants: "Team Meeting Notes" (8 people)
```
### 5. Keyword Cloud
```
Common Terms:
- meeting (45 occurrences)
- project (38 occurrences)
- update (31 occurrences)
- review (28 occurrences)
```
## Advanced Features
### Filtering Reports
Combine with read filters:
```bash
# Report on emails from specific sender
mailos read --from manager@company.com --days 30 | mailos report
# Report on unread emails
mailos read --unread --days 7 | mailos report
```
### Scheduled Reports
Create automated reports with cron:
```bash
# Weekly report every Monday
0 9 * * 1 mailos report --range "Last week" --output ~/reports/weekly-$(date +%Y%m%d).md
# Monthly report on the 1st
0 8 1 * * mailos report --range "Last month" --output ~/reports/monthly-$(date +%Y%m).md
```
### Comparison Reports
Generate multiple reports for comparison:
```bash
mailos report --range "This week" --output this-week.md
mailos report --range "Last week" --output last-week.md
# Compare the two reports
```
## Report Customization
### Environment Variables
* `MAILOS_REPORT_TIMEZONE`: Set report timezone
* `MAILOS_REPORT_FORMAT`: Default output format
* `MAILOS_REPORT_DETAIL`: Detail level (summary/normal/detailed)
### Configuration Options
In `.email/report-config.json`:
```json
{
"include_body_preview": false,
"max_senders_shown": 20,
"include_charts": true,
"timezone": "America/New_York"
}
```
## Use Cases
### 1. Productivity Analysis
Track email patterns to identify:
* Peak productivity hours
* Communication bottlenecks
* Response time patterns
### 2. Relationship Management
Monitor:
* Key contact frequency
* Neglected relationships
* Communication balance
### 3. Workload Assessment
Measure:
* Email volume trends
* Seasonal patterns
* Department communication
### 4. Inbox Zero Progress
Track:
* Daily email processing
* Unread accumulation
* Response rates
## Performance Considerations
* Reports analyze up to 1000 emails by default
* Large date ranges may take longer
* Cache results for 15 minutes
* Use specific ranges for faster generation
## Integration
### With Other Tools
Export reports for use in:
* Spreadsheet analysis (CSV export planned)
* Dashboard tools (JSON export planned)
* Document management systems
* Time tracking applications
### API Usage (Future)
```bash
# Get report as JSON
mailos report --range "Today" --format json
# Pipe to analysis tools
mailos report --range "This week" | grep "Total:" | awk '{print $2}'
```
## Tips
1. **Regular Reviews**: Generate weekly reports for pattern recognition
2. **Archive Reports**: Save monthly reports for long-term analysis
3. **Compare Periods**: Look for trends across multiple reports
4. **Focus Areas**: Use filters to report on specific senders or subjects
5. **Time Management**: Identify and minimize peak email times
## Troubleshooting
### Empty Reports
* Verify emails exist in time range: `mailos read --range "..."`
* Check timezone settings
* Ensure proper authentication
### Slow Generation
* Reduce time range
* Clear email cache: `rm -rf ~/.email/cache`
* Check network connection
### Incorrect Counts
* Verify filter settings
* Check for duplicate emails
* Ensure IMAP sync is complete
---
---
url: /repo.md
---
# EmailOS Repo Command Documentation
The `mailos repo` command shows repository-local email configuration and a send preview.
## Usage
```bash
mailos repo
```
## What it inspects
* `./.env.mailos`
* `./.env`
* nearest parent `emailos.json` or `emailos.toml`
* `./.email/config.json`
* Effective account/source resolution used by send flow
## Flags
| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--json` | bool | false | Output as JSON |
## Notes
* This command is informational and does not send email.
* Sensitive values are masked in output when applicable.
* When both env files exist, repo-local values are resolved from `./.env.mailos` first, then `./.env`.
* For send commands, `from_address` in the nearest parent `emailos.json` or `emailos.toml` overrides `MAILOS_FROM_EMAIL` and controls the project send account and outgoing `From` address.
* Use `mailos whoami` or `mailos config --values` for the compact resolved identity report.
---
---
url: /stats.md
---
# EmailOS Stats Command Documentation
The `mailos stats` command provides comprehensive email analytics and statistics with powerful filtering and aggregation capabilities.
## Basic Usage
```bash
mailos stats
```
This will analyze the last 100 emails and display comprehensive statistics.
## Command-Line Flags
### Basic Filters
| Flag | Short | Description | Example |
|------|-------|-------------|---------|
| `--number` | `-n` | Number of emails to analyze (default: 100) | `mailos stats -n 500` |
| `--unread` | `-u` | Analyze only unread emails | `mailos stats -u` |
| `--from` | | Filter by sender email address | `mailos stats --from john@example.com` |
| `--to` | | Filter by recipient email address | `mailos stats --to me@example.com` |
| `--subject` | | Filter by subject (partial match) | `mailos stats --subject invoice` |
| `--days` | | Analyze emails from last N days | `mailos stats --days 30` |
| `--range` | | Time range preset | `mailos stats --range "This week"` |
### Time Range Presets
The `--range` flag accepts the following presets:
* `"Last hour"` - Emails from the last hour
* `"Today"` - Today's emails
* `"Yesterday"` - Yesterday's emails
* `"This week"` - Current week's emails
* `"Last week"` - Previous week's emails
* `"This month"` - Current month's emails
* `"Last month"` - Previous month's emails
* `"This year"` - Current year's emails
## Advanced Query Parameters
You can pass additional parameters as key=value pairs after the command:
```bash
mailos stats [flags] [param1=value1] [param2=value2] ...
```
### Filter Parameters
| Parameter | Description | Example |
|-----------|-------------|---------|
| `from` | Filter by sender | `from=john@example.com` |
| `to` | Filter by recipient | `to=me@example.com` |
| `subject` | Filter by subject | `subject=invoice` |
| `limit`, `n` | Number of emails to analyze | `limit=500` |
| `days` | Emails from last N days | `days=30` |
| `range` | Time range preset | `range="Last week"` |
| `unread` | Only unread emails | `unread=true` |
| `sent` | Only sent emails | `sent=true` |
| `received` | Only received emails | `received=true` |
### Advanced Filters
| Parameter | Description | Example |
|-----------|-------------|---------|
| `attachments`, `has-attachments` | Only emails with attachments | `attachments=true` |
| `min-size` | Minimum email size | `min-size=10kb` |
| `max-size` | Maximum email size | `max-size=5mb` |
| `domain`, `domains` | Filter by sender domains (comma-separated) | `domains=gmail.com,outlook.com` |
| `exclude-domain`, `exclude-domains` | Exclude specific domains | `exclude-domains=spam.com,junk.com` |
| `keyword`, `keywords` | Must contain keywords (comma-separated) | `keywords=urgent,important` |
| `exclude`, `exclude-words` | Must not contain words | `exclude-words=spam,unsubscribe` |
### Size Format
Size parameters support the following formats:
* Bytes: `1000` or `1000b`
* Kilobytes: `10kb` or `10k`
* Megabytes: `5mb` or `5m`
* Gigabytes: `1gb` or `1g`
### Aggregation & Display Options
| Parameter | Description | Example |
|-----------|-------------|---------|
| `group-by`, `groupby` | Group results by field | `group-by=sender` |
| `sort-by`, `sortby`, `sort` | Sort results | `sort=date` |
| `format` | Output format | `format=json` |
| `top`, `top-n` | Number of top items to show | `top=20` |
## Complex Query Examples
### 1. Analyze large emails from specific domains in the last week
```bash
mailos stats range="Last week" domains=gmail.com,yahoo.com min-size=1mb
```
### 2. Find emails with attachments from specific senders
```bash
mailos stats from=john@example.com attachments=true days=30
```
### 3. Exclude spam and marketing emails
```bash
mailos stats exclude-words=unsubscribe,promotional exclude-domains=marketing.com days=7
```
### 4. Analyze urgent emails with keywords
```bash
mailos stats keywords=urgent,asap,important --days 3
```
### 5. Complex multi-filter query
```bash
mailos stats \
from=boss@company.com \
days=30 \
keywords=project,deadline \
min-size=5kb \
attachments=true \
top=20
```
### 6. Analyze emails by size range
```bash
mailos stats min-size=100kb max-size=10mb --days 14
```
### 7. Filter multiple domains with exclusions
```bash
mailos stats domains=company.com,partner.com exclude-domains=noreply.company.com
```
## Statistics Output
The stats command provides comprehensive analytics with **visual charts** using Unicode characters:
### Summary Statistics
* Total number of emails matching criteria
* Number of emails with attachments
* Average email size
### Top Senders
* Most frequent email senders
* Percentage of total emails
* Limited to top 10 by default (configurable with `top` parameter)
### Top Domains
* Most common sender domains
* Percentage distribution
* Shows top 10 domains
### Activity by Hour (Visual Chart)
* 24-hour distribution of email activity
* **Visual bar chart using Unicode blocks** (█▇▆▅▄▃▂▁)
* Shows peak email times at a glance
* Example output:
```
00:00 ▂▂ 2 emails
08:00 ████████ 24 emails
12:00 ██████ 18 emails
17:00 █████████ 28 emails
```
### Activity by Weekday (Visual Chart)
* Weekly email distribution with visual bars
* Shows which days are busiest
* Percentage breakdown by day
* Example output:
```
Monday ████████ 25%
Tuesday ██████ 18%
Wednesday ███████ 22%
```
### Top Subject Keywords
* Most common words in email subjects
* Excludes common words (the, and, for, etc.)
* Shows top 15 keywords with frequency
### Daily Distribution (Visual Timeline)
* Last 30 days of email activity
* **Visual bar chart showing daily trends**
* Helps identify patterns over time
* Displays as a timeline with Unicode bars
## Combining Flags and Parameters
You can combine command-line flags with query parameters:
```bash
mailos stats --unread --days 7 domains=important.com keywords=urgent
```
This will analyze unread emails from the last 7 days, from important.com domain, containing the word "urgent".
## Performance Tips
1. **Use specific filters**: The more specific your query, the faster the analysis
2. **Limit the number of emails**: Use `limit` or `-n` to analyze fewer emails for faster results
3. **Use time ranges**: Analyzing recent emails is faster than analyzing all emails
4. **Combine filters**: Multiple filters reduce the dataset size
## Output Formats
Currently supports:
* **Default**: Human-readable terminal output with visual charts
* **JSON**: Machine-readable format (use `format=json`)
## Use Cases
### 1. Email Volume Analysis
```bash
mailos stats --days 30
```
Understand your email patterns over the last month.
### 2. Sender Analysis
```bash
mailos stats from=client@company.com --days 90
```
Analyze communication patterns with specific contacts.
### 3. Attachment Tracking
```bash
mailos stats attachments=true --days 7
```
Find all emails with attachments from the last week.
### 4. Spam Detection
```bash
mailos stats exclude-words=unsubscribe,click,offer domains=suspicious.com
```
Identify potential spam patterns.
### 5. Important Email Monitoring
```bash
mailos stats keywords=urgent,important,asap --unread
```
Find critical unread emails.
### 6. Storage Analysis
```bash
mailos stats min-size=5mb
```
Find large emails consuming storage space.
## Notes
* All text searches are case-insensitive
* Domain filters match partial domains (e.g., `gmail.com` matches `mail.gmail.com`)
* Keywords search both subject and body content
* The stats command reads emails but does not modify them
* Results are based on locally cached email data after initial fetch
## Troubleshooting
If stats are not showing expected results:
1. Ensure your email account is properly configured: `mailos info`
2. Check that emails are being fetched: `mailos read -n 10`
3. Verify your filters are correct: Try broader filters first
4. Use the `--days` flag to ensure you're looking at the right time period
---
---
url: /validate.md
---
# Email Address Validation
The `validate` command checks if email addresses are likely deliverable before you send emails. This helps prevent bounce-backs and improves email deliverability.
## Overview
Email validation performs several checks to determine if an email address can receive messages:
1. **Syntax validation** - Checks if the email format is valid (RFC 5322 compliant)
2. **Domain validation** - Verifies the domain exists via DNS lookup
3. **MX record check** - Confirms the domain has mail server records configured
4. **SMTP verification** (optional) - Attempts to verify with the mail server directly
## Basic Usage
```bash
# Validate a single email address
mailos validate user@example.com
# Validate multiple email addresses
mailos validate user1@gmail.com user2@outlook.com user3@company.com
# Using the --email flag (can be repeated)
mailos validate --email user@example.com --email another@domain.com
```
## Command-Line Flags
### Basic Options
| Flag | Short | Type | Default | Description | Example |
|------|-------|------|---------|-------------|---------|
| `--email` | `-e` | \[]string | | Email address(es) to validate (can be repeated) | `mailos validate --email value` |
### Advanced Options
| Flag | Short | Type | Default | Description | Example |
|------|-------|------|---------|-------------|---------|
| `--full` | | bool | false | Perform full validation including SMTP check (slower) | `mailos validate --full` |
| `--quick` | | bool | false | Perform quick validation (syntax + MX only) | `mailos validate --quick` |
### Output Options
| Flag | Short | Type | Default | Description | Example |
|------|-------|------|---------|-------------|---------|
| `--json` | | bool | false | Output results as JSON | `mailos validate --json` |
| `--verbose` | `-v` | bool | false | Show detailed validation information | `mailos validate --verbose` |
## Command Flags
| Flag | Short | Type | Default | Description |
|------|-------|------|---------|-------------|
| `--email` | `-e` | string\[] | | Email address(es) to validate (can be repeated) |
| `--verbose` | `-v` | bool | false | Show detailed validation information |
| `--json` | | bool | false | Output results as JSON |
| `--full` | | bool | false | Perform full validation including SMTP check (slower) |
| `--quick` | | bool | false | Perform quick validation (syntax + MX only) |
## Examples
### Basic Validation
```bash
$ mailos validate john@example.com
Email Address Validation Results
================================
Checked at: 2025-01-15 10:30:45
john@example.com
--------------------------------
Summary: 1 valid, 0 invalid
```
### Verbose Output
```bash
$ mailos validate andrew@happysoft.dev invalid@nonexistent-domain.xyz --verbose
Email Address Validation Results
================================
Checked at: 2025-01-15 10:30:45
andrew@happysoft.dev
Syntax: OK | Domain: OK | MX: OK
Mail servers: in1-smtp.messagingengine.com, in2-smtp.messagingengine.com
Details: Email address appears to be valid and deliverable
invalid@nonexistent-domain.xyz - Domain does not exist
Syntax: OK | Domain: FAIL | MX: FAIL
Details: The domain 'nonexistent-domain.xyz' could not be found. DNS lookup failed.
--------------------------------
Summary: 1 valid, 1 invalid
```
### JSON Output
```bash
$ mailos validate user@gmail.com --json
```
```json
[
{
"email": "user@gmail.com",
"is_valid": true,
"syntax_valid": true,
"domain_valid": true,
"mx_valid": true,
"deliverable": true,
"details": "Email address appears to be valid and deliverable",
"mx_records": ["gmail-smtp-in.l.google.com", "alt1.gmail-smtp-in.l.google.com"],
"checked_at": "2025-01-15T10:30:45Z"
}
]
```
### Full SMTP Validation
For more thorough validation, use the `--full` flag which attempts to connect to the mail server:
```bash
$ mailos validate user@company.com --full --verbose
```
Note: SMTP verification can be slow and may be blocked by some mail servers. Many servers reject verification attempts for security reasons, so a failed SMTP check doesn't necessarily mean the address is invalid.
## Integration with Send Command
Email validation is **automatically enabled** when sending emails. The send command will validate all recipients before attempting to send.
```bash
# Validation happens automatically (enabled by default)
mailos send --to user@example.com --subject "Hello" --body "Hi there"
# Skip validation if needed
mailos send --to user@example.com --subject "Hello" --body "Hi there" --no-validate
# Force send even if validation fails
mailos send --to user@example.com --subject "Hello" --body "Hi there" --force
# Enable SMTP verification during send
mailos send --to user@example.com --subject "Hello" --body "Hi there" --validate-smtp
```
### Send Command Validation Flags
| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--validate` | bool | true | Validate recipient email addresses before sending |
| `--no-validate` | bool | false | Skip email address validation |
| `--validate-smtp` | bool | false | Perform SMTP verification during validation (slower) |
## Validation Results
### Valid Email
When an email passes all checks:
* Syntax is correct
* Domain exists and resolves
* MX records are configured
* (Optional) SMTP server accepts the address
### Invalid Email - Common Errors
| Error | Description |
|-------|-------------|
| `Invalid email syntax` | Email format doesn't match RFC 5322 standards |
| `Domain does not exist` | DNS lookup failed - domain may not exist or has expired |
| `No mail server found` | Domain has no MX records - cannot receive email |
| `Recipient rejected` | SMTP server explicitly rejected the address (full mode only) |
## Use Cases
### Pre-Send Validation
Validate a list of recipients before a bulk send:
```bash
# Validate all recipients first
mailos validate user1@a.com user2@b.com user3@c.com
# If all valid, proceed with send
mailos send --to user1@a.com,user2@b.com,user3@c.com --subject "Newsletter" --file newsletter.md
```
### Scripting and Automation
Use JSON output and exit codes for automation:
```bash
# Check exit code (0 = all valid, non-zero = some invalid)
if mailos validate user@example.com --json > /dev/null 2>&1; then
echo "Email is valid"
else
echo "Email is invalid"
fi
# Parse JSON output for detailed results
mailos validate user@example.com --json | jq '.[] | select(.deliverable == false)'
```
### Cleaning Email Lists
Validate a list of emails and filter out invalid ones:
```bash
# Read emails from file, validate, and output valid ones
cat emails.txt | xargs mailos validate --json | jq -r '.[] | select(.deliverable) | .email'
```
## Performance Notes
* **Quick mode** (`--quick`): Fastest, checks syntax and MX records only (~100ms per email)
* **Default mode**: Balanced, includes domain DNS verification (~200-500ms per email)
* **Full mode** (`--full`): Most thorough, includes SMTP verification (~1-5 seconds per email)
For bulk validation, consider using quick mode and only using full validation for critical addresses.
## Limitations
1. **SMTP verification is not definitive** - Many mail servers block verification attempts or give false positives/negatives
2. **Catch-all domains** - Some domains accept all addresses even if the mailbox doesn't exist
3. **Temporary failures** - DNS or network issues can cause false negatives
4. **Rate limiting** - Validating too many emails quickly may trigger rate limits
## Related Commands
* [send](send.md) - Send emails with automatic validation
* [drafts](drafts.md) - Create and manage email drafts
* [search](search.md) - Search for emails
---
---
url: /convert.md
---
# Convert Command
Use `mailos convert` to convert email files between supported formats.
## Usage
```bash
mailos convert [file-or-directory] [flags]
```
## Supported Input Formats
* `.eml`
* `.mbox`
* `.emlx`
* `.msg` (limited)
## Supported Output Formats
* `markdown`
* `json`
* `text`
* `eml`
* `html`
## Examples
```bash
mailos convert email.eml --format markdown
mailos convert archive.mbox --format json --pretty
mailos convert ./emails --format markdown --output-dir /output/converted
```
---
---
url: /unsubscribe.md
---
# EmailOS Unsubscribe Command Documentation
The `mailos unsubscribe` command finds and manages unsubscribe links in your email messages, helping you efficiently unsubscribe from unwanted mailing lists.
## Basic Usage
```bash
mailos unsubscribe [flags]
```
Searches through your emails to find unsubscribe links and provides options to manage them.
## Command-Line Flags
### Basic Options
| Flag | Short | Type | Default | Description | Example |
|------|-------|------|---------|-------------|---------|
| `--account` | | string | | Email account to use | `mailos unsubscribe --account value` |
| `--from` | | string | | Find unsubscribe links from sender(s) - comma-separated for batch processing | `mailos unsubscribe --from value` |
| `--number` | `-n` | int | 10 | Number of emails to check per sender | `mailos unsubscribe --number value` |
| `--subject` | | string | | Find unsubscribe links by subject | `mailos unsubscribe --subject value` |
### Advanced Options
| Flag | Short | Type | Default | Description | Example |
|------|-------|------|---------|-------------|---------|
| `--auto-open` | | bool | false | Automatically open unsubscribe link without prompting | `mailos unsubscribe --auto-open` |
| `--delete` | | bool | false | Delete emails after finding unsubscribe links | `mailos unsubscribe --delete` |
| `--move-to-folder` | | bool | false | Move emails with unsubscribe links to dedicated IMAP folder | `mailos unsubscribe --move-to-folder` |
| `--open` | | bool | false | Open the first unsubscribe link in browser | `mailos unsubscribe --open` |
| `--quiet` | `-q` | bool | false | Minimal output - only show count of emails found | `mailos unsubscribe --quiet` |
### Output Options
| Flag | Short | Type | Default | Description | Example |
|------|-------|------|---------|-------------|---------|
| `--dry-run` | | bool | false | Show what would be deleted without actually deleting | `mailos unsubscribe --dry-run` |
| `--json` | | bool | false | Output results as JSON for programmatic use | `mailos unsubscribe --json` |
## Features
### Intelligent Link Detection
The command uses multiple detection methods to find unsubscribe links:
* **Header-based**: Checks RFC 2369/8058 `List-Unsubscribe` headers
* **URL patterns**: Searches for common unsubscribe URL patterns
* **Link text analysis**: Finds links with unsubscribe-related text
* **Service-specific**: Recognizes patterns from popular email services (MailChimp, SendGrid, etc.)
### Supported Email Services
Optimized detection for major email marketing platforms:
* Beehiiv
* MailChimp
* SendGrid
* ConvertKit
* Constant Contact
* Campaign Monitor
* AWeber
* GetResponse
* ActiveCampaign
* HubSpot
* Pardot
* Marketo
## Usage Examples
### Basic Search
```bash
# Find unsubscribe links in last 10 emails
mailos unsubscribe
# Check more emails
mailos unsubscribe --number 50
```
### Targeted Search
```bash
# Find links from specific sender
mailos unsubscribe --from "newsletter@company.com"
# Search by subject pattern
mailos unsubscribe --subject "Weekly Update"
```
### Email Management
```bash
# Move emails with unsubscribe links to dedicated folder
mailos unsubscribe --move-to-folder
# Automatically open first unsubscribe link found
mailos unsubscribe --auto-open
```
### Combined Operations
```bash
# Find, organize, and open unsubscribe links
mailos unsubscribe --from "[MARKETING_SENDER]" --move-to-folder --open
```
## Output Format
The command provides a detailed report showing:
* Email sender and subject
* All unsubscribe links found
* Count of emails processed
Example output:
```
Searching for unsubscribe links...
Found unsubscribe links in 3 emails:
1. From: newsletter@example.com
Subject: Weekly Newsletter - October 2024
Unsubscribe links:
- https://example.com/unsubscribe?id=12345
- https://example.com/preferences?email=user@domain.com
2. From: [MARKETING_SENDER]
Subject: Special Offer Inside!
Unsubscribe links:
- https://store.com/opt-out?token=abcdef
```
## Folder Management
When using `--move-to-folder`, the command:
* Creates an "Unsubscribe" folder if it doesn't exist
* Moves all emails containing unsubscribe links to this folder
* Provides feedback on the number of emails moved
## Safety and Privacy
* **Read-only scanning**: The command only reads email content for analysis
* **No automatic actions**: Requires explicit flags for actions like opening links or moving emails
* **User confirmation**: Interactive prompts for potentially destructive actions
* **Clean URL extraction**: Removes tracking parameters and validates URLs
## Integration with Other Commands
The unsubscribe command works well with other EmailOS features:
```bash
# First search and organize
mailos unsubscribe --move-to-folder
# Then read the organized emails
mailos read --folder "Unsubscribe"
# Generate statistics on unsubscribe patterns
mailos stats --folder "Unsubscribe"
```
## Tips and Best Practices
1. **Regular cleanup**: Run `mailos unsubscribe --move-to-folder` regularly to keep your inbox organized
2. **Bulk processing**: Use higher `--number` values for thorough cleanup sessions
3. **Targeted cleanup**: Use `--from` filters when dealing with specific senders
4. **Safe browsing**: Review unsubscribe links before opening them, especially from unknown senders
## Troubleshooting
### No Links Found
* Try increasing `--number` to check more emails
* Use `--from` or `--subject` filters to target specific emails
* Some emails may use non-standard unsubscribe methods
### Browser Opening Issues
* Ensure your system has a default web browser configured
* Use `--open` for interactive confirmation instead of `--auto-open`
* Copy and paste links manually if automatic opening fails
### IMAP Folder Issues
* Verify your email provider supports IMAP folder creation
* Check that you have write permissions for your email account
* Some providers may have folder name restrictions
---
---
url: /uninstallation.md
---
# EmailOS Complete Uninstallation Guide
This guide provides comprehensive instructions for completely removing EmailOS from your system, including all configuration files, email data, and system traces.
## TL;DR - Quick Complete Removal
```bash
# One-command complete uninstallation with backup
mailos uninstall --backup
# Or force removal without confirmation
mailos uninstall --force
```
## Understanding EmailOS Data
EmailOS stores data in several locations:
### Primary Data Location
* **`~/.email/`** - Main directory containing:
* `config.json` - Account configuration and credentials
* `sent/` - Copies of sent emails
* `received/` - Synced received emails
* `drafts/` - Draft emails
* `.license` - License information
### Secondary Locations
* **`.email/`** - Local project configurations (optional)
* **`EMAILOS.md`** - AI integration files in project directories
## Complete Uninstallation Methods
### Method 1: Built-in Uninstall Command (Recommended)
EmailOS includes a comprehensive uninstall command that handles all cleanup automatically:
#### Basic Uninstallation
```bash
# Interactive uninstallation with confirmation
mailos uninstall
# Silent uninstallation without prompts
mailos uninstall --force
# See what would be removed without doing it
mailos uninstall --dry-run
```
#### Advanced Options
```bash
# Create backup before removal
mailos uninstall --backup
# Specify custom backup location
mailos uninstall --backup --backup-path ~/Desktop/emailos-backup
# Keep email data, only remove configuration
mailos uninstall --keep-emails
# Keep configuration, only remove email data
mailos uninstall --keep-config
# Minimal output
mailos uninstall --quiet
```
### Method 2: Package Manager + Cleanup
If you prefer using your package manager:
#### npm
```bash
# Uninstall binary (will prompt for data removal)
npm uninstall -g mailos
# If prompted, choose to remove data or clean up manually later
```
#### Homebrew
```bash
# Remove binary
brew uninstall mailos
# Clean up remaining data
mailos cleanup # if command still works
# OR manually: rm -rf ~/.email
```
#### Manual Binary Removal
```bash
# Find and remove binary
sudo rm $(which mailos)
# Clean up data
rm -rf ~/.email
```
## Handling Orphaned Data
Sometimes EmailOS data remains after external uninstallation. EmailOS automatically detects this situation:
### Automatic Detection
* EmailOS shows hints when orphaned data is detected
* Runs periodic checks for orphaned configurations
* Provides guidance for cleanup
### Manual Cleanup
```bash
# Check for orphaned data
ls -la ~/.email
# If EmailOS binary is still available
mailos cleanup
# If binary is gone, download cleanup tool
curl -L https://github.com/anduimagui/emailos-cli/releases/latest/download/mailos-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m).tar.gz | tar xz
./mailos cleanup
rm ./mailos
# Or manual removal
rm -rf ~/.email
find ~ -name ".email" -type d -exec rm -rf {} + 2>/dev/null
```
## Backup and Recovery
### Creating Backups
```bash
# Manual backup before removal
cp -r ~/.email ~/emailos-backup-$(date +%Y%m%d)
# Automatic backup during uninstall
mailos uninstall --backup
# Custom backup location
mailos uninstall --backup --backup-path /path/to/backup
```
### Recovering Data
```bash
# Check if data still exists
ls -la ~/.email
# Restore from backup
cp -r ~/emailos-backup-YYYYMMDD ~/.email
# Reinstall EmailOS to access recovered data
npm install -g mailos
```
## Verification and Troubleshooting
### Verify Complete Removal
```bash
# Check for EmailOS binary
which mailos 2>/dev/null && echo "Binary still exists" || echo "✓ Binary removed"
# Check for configuration data
ls -la ~/.email 2>/dev/null && echo "Data still exists" || echo "✓ Data removed"
# Check for local project configs
find ~ -name ".email" -type d 2>/dev/null | head -10
# Check for AI integration files
find ~ -name "EMAILOS.md" 2>/dev/null | head -10
```
### Common Issues
#### Permission Denied
```bash
# If you can't remove ~/.email
sudo rm -rf ~/.email
# If you can't remove the binary
sudo rm $(which mailos)
```
#### Partial Uninstallation
```bash
# If uninstallation was interrupted, reinstall temporarily
npm install -g mailos
# Complete the uninstallation
mailos uninstall --force
# Remove binary again
npm uninstall -g mailos
```
#### Hidden Files
```bash
# Check for hidden EmailOS files
find ~ -name ".*email*" -o -name ".*mailos*" 2>/dev/null
# Remove if found
rm -rf ~/.email ~/.mailos ~/.emailos
```
#### Process Still Running
```bash
# Check for running EmailOS processes
ps aux | grep mailos
# Kill if necessary
pkill -f mailos
```
## Platform-Specific Instructions
### macOS
```bash
# Standard uninstallation
mailos uninstall --backup
# Manual cleanup
rm -rf ~/.email
rm -f /usr/local/bin/mailos
rm -f /opt/homebrew/bin/mailos
# Check LaunchAgents (if any)
ls ~/Library/LaunchAgents/*mailos* 2>/dev/null
```
### Linux
```bash
# Standard uninstallation
mailos uninstall --backup
# Manual cleanup
rm -rf ~/.email
rm -f /usr/local/bin/mailos
rm -f ~/.local/bin/mailos
# Check systemd services (if any)
systemctl --user list-units | grep mailos
```
### Windows
```powershell
# Standard uninstallation
mailos uninstall --backup
# Manual cleanup
Remove-Item -Recurse -Force "$env:USERPROFILE\.email"
Remove-Item "C:\Program Files\mailos\mailos.exe"
# Check scheduled tasks (if any)
Get-ScheduledTask | Where-Object {$_.TaskName -like "*mailos*"}
```
## Security Considerations
### Sensitive Data Removal
EmailOS configuration contains sensitive information:
* Email app passwords
* License keys
* Account credentials
Ensure complete removal:
```bash
# Secure deletion (Linux/macOS)
rm -P ~/.email/config.json # macOS
shred -u ~/.email/config.json # Linux
# Or use the built-in secure cleanup
mailos uninstall --force
```
### Backup Security
If creating backups:
* Store in secure location
* Encrypt if necessary
* Delete when no longer needed
```bash
# Encrypted backup
tar czf - ~/.email | gpg -c > emailos-backup-$(date +%Y%m%d).tar.gz.gpg
# Secure backup deletion
rm -P emailos-backup-*.tar.gz.gpg # macOS
shred -u emailos-backup-*.tar.gz.gpg # Linux
```
## Reinstallation
If you need to reinstall EmailOS later:
```bash
# Reinstall via npm
npm install -g mailos
# Restore from backup if needed
cp -r ~/emailos-backup-YYYYMMDD ~/.email
# Run setup if starting fresh
mailos setup
```
## Support
If you encounter issues during uninstallation:
1. **Try the automated cleanup**: `mailos cleanup`
2. **Check the troubleshooting section** above
3. **Report issues**: https://github.com/anduimagui/emailos-cli/issues
4. **Manual cleanup**: Remove files manually as documented
## Complete Uninstallation Checklist
* \[ ] Run `mailos uninstall --backup`
* \[ ] Verify binary removal: `which mailos`
* \[ ] Verify data removal: `ls ~/.email`
* \[ ] Check for local configs: `find ~ -name ".email" -type d`
* \[ ] Check for EMAILOS.md files: `find ~ -name "EMAILOS.md"`
* \[ ] Secure backup if needed
* \[ ] Update package manager if required
✅ **Complete!** EmailOS has been fully removed from your system.
---
---
url: /changelog.md
---
# Changelog
Updates to EmailOS, organized by week.
## Week of May 18, 2026
### New
* **`mailos whoami` for resolved send identity.** Run `mailos whoami` from any project folder to see exactly which `From` address, signature, and credentials `mailos send` will use, along with the source each value resolved from. See [Env Command](env.md#related-commands).
* **`mailos env --export` for shell-safe send defaults.** Emits non-secret send values (`MAILOS_EMAIL_ADDRESS`, `MAILOS_FROM_EMAIL`, `MAILOS_FROM_NAME`) as `export` statements so AI clients, IDE integrations, and other tools that only read real environment variables can pick up values resolved from a project `emailos.json`. Run `eval "$(mailos env --export)"`. Secrets are never exported. See [Env Command](env.md#export-for-ai-clients).
* **Apple Mail forwarded context in `mailos send`.** When you paste forwarded content copied from Apple Mail into a send body, EmailOS now detects the forwarded headers and threads the outgoing message correctly. See [Forward Command](forward.md) and [Send Command](send.md).
* **Forward from a macOS Mail deeplink.** `mailos send --forward-message-link` accepts `message://...` links copied from Mail.app or Raycast, while `--forward-message-id` remains the portable raw Message-ID option. See [macOS Mail Integration](clients/macos-mail.md) and [Send Command](send.md).
### Updates
* **Project sender policy is now authoritative.** When the nearest `emailos.json` sets `from_address`, it controls the outgoing `From` address for `mailos send` and overrides `MAILOS_FROM_EMAIL`. Passing `--from` or `--account` no longer changes the sender for a project that pins one — the CLI warns and keeps the project value. Update `emailos.json` to change the sender. See [File Config](file-config.md#send-defaults) and [Send Command](send.md).
* **`mailos repo` now reports `emailos.json`.** The repo diagnostic command lists the project config alongside `.env.mailos`, `.env`, and `./.email/config.json`, so you can see at a glance which files contribute to send resolution. See [Repo Command](repo.md).
### Fixes
* **Better spacing before inline attachment previews.** Send output now includes consistent spacing before inline attachment previews, making the rendered email easier to read.
* **More reliable Apple Mail deeplinks.** MailOS now emits fully encoded `message://%3c...%3e` links and checks the selected Mail message before slower mailbox scans when resolving Apple Mail forwarding context.
---
---
url: /clients/macos-mail.md
---
# macOS Mail Integration
This guide explains how EmailOS integrates with Apple Mail on macOS for Message-ID links, message deeplinks, forwarding, and attachment export.
## What works
* Read by Message-ID from Apple Mail-style links (`message://...`).
* Convert/canonicalize Message-ID links from Apple Mail into lookup-safe IDs.
* Generate and open Apple Mail deep links with:
* `mailos read --message-id "<...>" --message-link`
* `mailos read --message-id "<...>" --open-message-link`
* Forward a known Apple Mail message with:
* `mailos send --forward-message-link "message://..."`
* Save attachments directly while reading:
* `mailos read --message-id "message://..." --save-attachments /Users//output/attachments/ --markdown`
## Message-ID vs message link
A Message-ID is the cross-platform email header value, for example ``. A macOS Mail message link wraps that ID in a `message://...` URL so Mail.app can open it, for example `message://%3cabc%40example.com%3e`.
Use `--forward-message-id` when you have the raw Message-ID. Use `--forward-message-link` when you copied a macOS Mail deeplink from Mail.app, Raycast, or the repo AppleScript helpers.
## Message-ID lookup behavior
EmailOS uses two Message-ID modes in `read`:
* `--message-id `: auto sync+retry on miss, then Apple Mail fallback on macOS.
* Positional Message-ID (`mailos read ""`): no auto sync by default.
* Use `--sync` to force sync+retry for positional IDs.
Examples:
```bash
# Apple Mail URL input
mailos read --message-id "message://%3cabc%40example.com%3e" --markdown
# Positional Message-ID with explicit sync
mailos read "" --sync --markdown
```
## Forwarding from a macOS Mail link
```bash
mailos send \
--to colleague@example.com \
--subject "FYI" \
--body "Adding this for context." \
--forward-message-link "message://%3cabc%40example.com%3e" \
--dry-run
```
`--forward-message-link` and `--forward-message-id` use the same lookup path after normalization. If both are provided and point to different messages, `mailos send` exits with an error instead of guessing.
## Attachment export on macOS
`--save-attachments` now supports a macOS fallback path via Mail.app when attachment bytes are not present in the primary read payload.
That means the command can still export files from Mail.app by Message-ID and append paths to markdown output:
```bash
mailos read --message-id "message://%3cabc%40example.com%3e" \
--save-attachments "/Users//output/attachments/case-123" \
--markdown
```
Expected footer in output:
```text
---
Attachments saved to:
- /Users//output/attachments/case-123/file.pdf
- /Users//output/attachments/case-123/image001.png
```
## Clipboard workflow (Raycast / script)
If you use a helper script like `copy-mail-id.sh`, keep script logic thin and delegate to `mailos`:
* Copy an encoded Mail deeplink with `copy-mail-id.sh`; set `COPY_MAIL_ID_FORMAT=message-id` only when you need the raw Message-ID.
* `copy-mail-content.sh` copies both a `DEEPLINK` block and `CONTENT` block by default; set `COPY_MAIL_CONTENT_INCLUDE_DEEPLINK=0` for content only.
* Resolve/read via `mailos read --message-id ... --markdown`
* Include `--save-attachments ` so output contains paths
* For clipboard pipelines, add `--suppress-attachment-errors` to avoid timeout text in copied markdown
* Copy command output directly to clipboard
This avoids duplicate AppleScript logic and keeps behavior consistent with CLI updates.
## Troubleshooting
* **Message not found**
* Retry with `--message-id` form (auto sync+retry), or run `mailos sync` then retry.
* **No attachment paths in output**
* Ensure `--save-attachments` points to a writable directory.
* Confirm the message actually has attachments (not only remote/cid references).
* **Apple Mail lookup timeouts**
* Retry once after `mailos sync`.
* Keep Mail.app open and account/mailbox data fully loaded.
* Use `--attachment-timeout ` to fail fast (for example `--attachment-timeout 15`).
* **Wrong binary used by automation**
* Pin automation to the intended binary path (for example `/Users/andrewmaguire/go/bin/mailos`).
---
---
url: /config.md
---
# EmailOS Configure Command Documentation
The `mailos configure` command manages email account configuration with support for both global and local (project-specific) settings.
## Basic Usage
```bash
mailos configure
```
Interactive configuration wizard for setting up or modifying email settings.
## Command-Line Flags
### Basic Options
| Flag | Short | Type | Default | Description | Example |
|------|-------|------|---------|-------------|---------|
| `--email` | | string | | Email address to configure | `mailos config --email value` |
### Advanced Options
| Flag | Short | Type | Default | Description | Example |
|------|-------|------|---------|-------------|---------|
| `--aicli` | | string | | Default AI CLI (claude-code, openai-codex, gemini-cli) | `mailos config --aicli value` |
| `--backup` | | bool | false | Create backup before modifying | `mailos config --backup` |
| `--env` | | bool | false | Manage environment variables interactively | `mailos config --env` |
| `--env-email` | | string | | Set MAILOS\_EMAIL\_ADDRESS in local .env file | `mailos config --env-email value` |
| `--env-license` | | string | | Set MAILOS\_LICENSE\_KEY in local .env file | `mailos config --env-license value` |
| `--env-password` | | string | | Set MAILOS\_APP\_PASSWORD in local .env file | `mailos config --env-password value` |
| `--env-picture` | | string | | Set MAILOS\_PICTURE in local .env file | `mailos config --env-picture value` |
| `--env-signature` | | string | | Set MAILOS\_SIGNATURE in local .env file | `mailos config --env-signature value` |
| `--export` | | string | | Export configuration to file | `mailos config --export value` |
| `--force` | | bool | false | Force configuration without confirmation | `mailos config --force` |
| `--image` | | string | | Profile image URL | `mailos config --image value` |
| `--imap-host` | | string | | Custom IMAP host | `mailos config --imap-host value` |
| `--imap-port` | | int | 0 | Custom IMAP port | `mailos config --imap-port value` |
| `--license` | | string | | EmailOS license key | `mailos config --license value` |
| `--local` | | bool | false | Create local project configuration | `mailos config --local` |
| `--name` | | string | | Display name for emails | `mailos config --name value` |
| `--oauth2` | | bool | false | Use OAuth2 authentication (required for Microsoft Exchange/Outlook) | `mailos config --oauth2` |
| `--oauth2-auth-code` | | string | | OAuth2 authorization code from callback URL | `mailos config --oauth2-auth-code value` |
| `--oauth2-auto-open` | | bool | false | Automatically open browser for OAuth2 authorization | `mailos config --oauth2-auto-open` |
| `--oauth2-client-id` | | string | | OAuth2 Client ID from Azure App Registration | `mailos config --oauth2-client-id value` |
| `--oauth2-client-secret` | | string | | OAuth2 Client Secret from Azure App Registration | `mailos config --oauth2-client-secret value` |
| `--oauth2-manual` | | bool | false | Use manual OAuth2 flow (show instructions instead of auto callback) | `mailos config --oauth2-manual` |
| `--oauth2-redirect-uri` | | string | http://localhost:3000/auth/callback | OAuth2 redirect URI | `mailos config --oauth2-redirect-uri value` |
| `--oauth2-tenant-id` | | string | common | Azure Tenant ID (use 'common' for multi-tenant apps) | `mailos config --oauth2-tenant-id value` |
| `--preview-auto-delete` | | bool | false | Auto-delete temporary EML files after use | `mailos config --preview-auto-delete` |
| `--preview-auto-open` | | bool | false | Automatically open EML files in mail client | `mailos config --preview-auto-open` |
| `--preview-cleanup-time` | | int | 0 | Auto-cleanup time for temp files in seconds (default: 300) | `mailos config --preview-cleanup-time value` |
| `--preview-enabled` | | bool | false | Enable email preview functionality | `mailos config --preview-enabled` |
| `--preview-force-eml` | | bool | false | Force EML fallback instead of native client integration | `mailos config --preview-force-eml` |
| `--preview-include-headers` | | bool | false | Include email headers in EML files | `mailos config --preview-include-headers` |
| `--preview-output-dir` | | string | | Default directory for EML exports | `mailos config --preview-output-dir value` |
| `--preview-temp-prefix` | | string | | Prefix for temporary EML files (default: mailos\_preview\_) | `mailos config --preview-temp-prefix value` |
| `--provider` | | string | | Email provider (gmail, fastmail, outlook, yahoo, zoho) | `mailos config --provider value` |
| `--quick` | | bool | false | Quick configuration menu | `mailos config --quick` |
| `--show-diff` | | bool | false | Show configuration differences | `mailos config --show-diff` |
| `--smtp-host` | | string | | Custom SMTP host | `mailos config --smtp-host value` |
| `--smtp-port` | | int | 0 | Custom SMTP port | `mailos config --smtp-port value` |
| `--test` | | bool | false | Test configuration after setup | `mailos config --test` |
| `--update-gitignore` | | bool | false | Automatically update .gitignore to exclude .email directory | `mailos config --update-gitignore` |
| `--validate-only` | | bool | false | Validate configuration without saving | `mailos config --validate-only` |
| `--values` | | bool | false | Show resolved project send values from env files and nearest parent project config | `mailos config --values` |
## Configuration Types
### Global Configuration
Located at `~/.email/config.json`
* Used by default for all EmailOS commands
* Shared across all projects
* Contains full email credentials
* Stores multiple account configurations
Set `MAILOS_CONFIG_PATH` to use a different global account config file:
```bash
export MAILOS_CONFIG_PATH=/absolute/path/to/config.json
```
This is useful from direnv-managed repositories:
```bash
# .envrc
export MAILOS_CONFIG_PATH="$PWD/.private/emailos-config.json"
```
Local `./.email/config.json` still wins when present, but missing fields inherit from the `MAILOS_CONFIG_PATH` file instead of `~/.email/config.json`.
### Local Configuration
Located at `./.email/config.json`
* Project-specific settings
* Inherits from global configuration
* Override specific fields like display name or from address
* Automatically added to `.gitignore`
### Local Email Aliases
**New Feature**: EmailOS now supports creating local email aliases that inherit authentication from global accounts:
* **Automatic Detection**: When setting up a local config with `--email`, EmailOS checks if the email already exists in your global configuration
* **Seamless Inheritance**: Aliases inherit provider settings and authentication without requiring new passwords
* **Minimal Configuration**: Only stores alias-specific settings (display name, from address)
* **Smart Setup**: Creates aliases for emails in global accounts array or matching the main global email
#### Alias vs Full Configuration
| Setup Type | Requirement | Authentication | Use Case |
|------------|------------|----------------|----------|
| **Local Alias** | Email exists in global config | Inherited | Project-specific identity using existing account |
| **Full Local Config** | New email address | Full setup required | Completely separate email account |
## Configuration Inheritance
Local configs inherit from global settings:
```
Global Config (~/. email/):
- provider: gmail
- email: user@gmail.com
- password: ****
- from_name: Your Name
Local Config (./.email/):
- from_name: Project Bot # Overrides global
- from_email: bot@example.com # Project-specific sender
```
## Smart Provider Detection
EmailOS includes intelligent provider detection that automatically identifies your email provider using multiple methods:
### Detection Methods
1. **Domain Recognition**: Direct domain matching for known providers
* `@gmail.com` → Gmail
* `@fastmail.com` → Fastmail
* `@outlook.com` → Outlook
* `@yahoo.com` → Yahoo
* `@icloud.com` → iCloud
2. **MX Record Lookup**: DNS queries for custom domains
* Checks MX records to identify hosting provider
* Detects services like:
* `messagingengine.com` → Fastmail
* `google.com` → Gmail (G Suite/Workspace)
* `outlook.com` → Microsoft 365
* `yahoo.com` → Yahoo Business
3. **Provider Validation**: Cross-references user input against detection
* Warns when `--provider` flag conflicts with MX records
* Confirms when provider choice matches infrastructure
### Detection Examples
```bash
# Auto-detection for known domains
mailos configure --email "user@gmail.com"
# ✓ Auto-detected provider: Gmail (via domain)
# MX record detection for custom domains
mailos configure --email "user@company.com"
# ✓ Auto-detected provider: Gmail (via MX record)
# Provider validation with mismatch warning
mailos configure --email "user@company.com" --provider fastmail
# ⚠️ Provider mismatch detected!
# You specified: Fastmail
# MX records indicate: Gmail (via MX record)
# Continuing with your choice: Fastmail
# Provider confirmation when correct
mailos configure --email "user@company.com" --provider gmail
# ✓ Provider confirmed: Gmail matches MX records (MX record)
```
## Supported Providers
| Provider | Configuration Key | Notes |
|----------|------------------|-------|
| Gmail | `gmail` | Requires app-specific password |
| Outlook | `outlook` | Includes Hotmail, Live.com |
| Yahoo | `yahoo` | Requires app password |
| iCloud | `icloud` | Apple Mail |
| ProtonMail | `proton` | Bridge required |
| Fastmail | `fastmail` | App password recommended |
| Custom | `custom` | Manual SMTP/IMAP settings |
## AI CLI Providers
| Provider | Key | Description |
|----------|-----|-------------|
| Claude Code | `claude-code` | Claude via VS Code |
| Claude Yolo | `claude-code-yolo` | Claude without confirmations |
| OpenAI | `openai` | ChatGPT integration |
| Gemini | `gemini` | Google AI |
| OpenCode | `opencode` | Open source alternative |
| None | `none` | Disable AI features |
## Interactive Mode
Running `mailos configure` without flags starts interactive setup:
1. **Provider Selection**: Choose your email service
2. **Email Address**: Enter your email
3. **App Password**: Enter app-specific password
4. **Display Name**: Optional sender name
5. **Profile Image**: Optional profile image path
6. **From Email**: Optional custom sender address
7. **AI Provider**: Select AI integration
## Quick Configuration
```bash
mailos configure --quick
```
Provides a menu for quick changes:
* Update password
* Change display name
* Switch AI provider
* Modify from address
## Examples
### Initial Setup
```bash
mailos configure
# Follow interactive prompts
```
### Create Local Configuration
```bash
mailos configure --local
# Creates .email/config.json in current directory
```
### Create Local Email Alias (New Feature)
```bash
# If an alias exists in your global accounts
mailos configure --local --email alias@example.com --name "My alias"
# Output:
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# CREATE LOCAL EMAIL ALIAS
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# 📧 Setting up email as a local alias (found in global accounts)
# Using Fastmail provider, authentication inherited from global config.
#
# ✓ Created local alias: alias@example.com
# ✓ Display name: My alias
#
# 📁 Local configuration saved to .email/config.json
# 🔐 Authentication will be inherited from global config
```
### Direct Configuration
```bash
# Complete single-command setup (only prompts for app password)
mailos configure \
--email user@gmail.com \
--provider gmail \
--name "Your Name" \
--license "lic_abc123"
# Auto-detection (provider detected automatically)
mailos configure \
--email user@gmail.com \
--name "Your Name" \
--ai claude-code
# Explicit provider with validation
mailos configure \
--email john@company.com \
--provider gmail \
--name "Your Name" \
--image /Users/john/profile.jpg
# Force overwrite existing config
mailos configure \
--email user@gmail.com \
--name "Your Name" \
--force
```
### Project-Specific Sender
```bash
# In project directory - traditional local config
mailos configure --local \
--from noreply@example.com \
--name "Project Notifications"
# Using email alias (if exists in global config) - New Feature
mailos configure --local \
--email team@company.com \
--name "Project Team" \
--from team@example.com
```
### Update Password Only
```bash
mailos configure --quick
# Select "Update Password" from menu
```
### Advanced Examples
```bash
# Complete setup with all options
mailos configure \
--email "support@company.com" \
--name "Company Support" \
--from "noreply@company.com" \
--image "/opt/company/logo.png" \
--ai claude-code \
--backup \
--test
# Custom domain with provider detection
mailos configure --email "user@example.com"
# EmailOS will check MX records and detect the actual provider
# Local project configuration with backup
mailos configure --local \
--name "Project Bot" \
--from "bot@example.com" \
--backup
# Force update without prompts
mailos configure \
--email "admin@company.com" \
--provider gmail \
--force
# Validate configuration without saving
mailos configure \
--email "user@company.com" \
--name "Test User" \
--validate-only
# Export current configuration
mailos configure --export "backup-$(date +%Y%m%d).json"
# Show differences before applying changes
mailos configure \
--email "user@company.com" \
--name "New Name" \
--diff
# Test configuration with connection validation
mailos configure \
--email "user@gmail.com" \
--name "Test User" \
--test
# Custom provider with specific ports
mailos configure \
--email "user@example.com" \
--provider custom \
--smtp-host "smtp.custom.com" \
--smtp-port 587 \
--imap-host "imap.custom.com" \
--imap-port 993
```
## Local Email Alias Workflow (New Feature)
### How Email Aliases Work
EmailOS now intelligently detects when you're setting up a local configuration for an email address that already exists in your global configuration. Instead of requiring full authentication setup, it creates a lightweight alias:
#### Automatic Alias Detection
```bash
# Scenario: You have john@company.com in your global accounts
mailos configure --local --email john@company.com --name "Project Lead"
# EmailOS detects the existing account and creates an alias:
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# CREATE LOCAL EMAIL ALIAS
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# 📧 Setting up john@company.com as a local alias (found in global accounts)
# Using Gmail provider, authentication inherited from global config.
```
#### Alias Configuration Structure
The resulting local configuration is minimal and secure:
```json
{
"provider": "",
"email": "john@company.com",
"password": "",
"from_name": "Project Lead",
"from_email": "john@company.com",
"ai_provider": {
"ollama": {},
"vllm": {}
}
}
```
**Key Benefits:**
* **No passwords stored locally** - Authentication inherited from global config
* **Minimal file size** - Only alias-specific settings saved
* **Instant setup** - No need to re-enter credentials
* **Secure** - No sensitive data in project directories
#### When Aliases Are Created
EmailOS creates aliases automatically when:
1. **Email exists in global accounts array**:
```bash
# If your ~/.email/config.json has this email in accounts[]
mailos configure --local --email team@company.com
```
2. **Email matches main global email**:
```bash
# If your main email is primary@company.com
mailos configure --local --email primary@company.com
```
3. **Same provider detection**:
* EmailOS detects the provider for the requested email
* If it matches an existing account's provider, alias creation is preferred
#### Alias vs Full Setup Examples
```bash
# ✅ ALIAS CREATION (email exists in global config)
mailos configure --local --email existing@company.com --name "Project Bot"
# → Creates alias, inherits authentication
# ❌ FULL SETUP (new email address)
mailos configure --local --email user@example.com --name "New Account"
# → Requires full setup including app password
```
### Alias Management Best Practices
#### 1. Use Aliases for Project-Specific Identities
```bash
# Different projects, same email account
cd ~/projects/client-a
mailos configure --local --email consultant@company.com --name "Client A Consultant"
cd ~/projects/client-b
mailos configure --local --email consultant@company.com --name "Client B Consultant"
```
#### 2. Customize From Addresses
```bash
# Use alias with custom from address
mailos configure --local \
--email john@company.com \
--name "Support Team" \
--from support@example.com
```
#### 3. Inherit Settings from Existing Accounts
```bash
# If your global config has specific settings for team@company.com,
# the alias will inherit display name and other preferences
mailos configure --local --email team@company.com
# Override inherited settings as needed
mailos configure --local \
--email team@company.com \
--name "Custom Project Name"
```
## Advanced Configuration Features
### Configuration Validation
Use `--validate-only` to test configuration without saving:
```bash
mailos configure \
--email "user@company.com" \
--provider gmail \
--name "Test User" \
--validate-only
# Output:
✅ Configuration validation successful!
📋 Configuration preview:
Email: user@company.com
Provider: Gmail
Display Name: Test User
💾 Note: Configuration was NOT saved (--validate-only mode)
```
### Connection Testing
Use `--test` to validate SMTP/IMAP connectivity:
```bash
mailos configure \
--email "user@gmail.com" \
--name "Test User" \
--test
# Output:
🔧 Testing email configuration...
🔍 Testing SMTP connection to smtp.gmail.com:587...
✅ SMTP configuration appears valid
🔍 Testing IMAP connection to imap.gmail.com:993...
✅ IMAP configuration appears valid
✅ Configuration test successful!
```
### Configuration Export/Backup
Export current configuration for backup or migration:
```bash
# Export global configuration
mailos configure --export "global-backup.json"
# Export local configuration
mailos configure --local --export "project-backup.json"
# Output:
📤 Exporting global configuration (~/.email/config.json)...
✅ Configuration exported to: global-backup.json
⚠️ Warning: This file contains sensitive information (passwords).
Store it securely and consider encrypting it.
```
### Configuration Diff Preview
See changes before applying them:
```bash
mailos configure \
--email "user@company.com" \
--name "New Display Name" \
--diff
# Output:
📊 Configuration Differences:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📝 Updating GLOBAL configuration
FIELD CURRENT → NEW
───── ───────────────
Display Name Your Name → New Display Name
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📝 Apply these changes? (y/N):
```
### Custom Provider Setup
Configure custom email providers with specific hosts and ports:
```bash
mailos configure \
--email "user@company.com" \
--provider custom \
--smtp-host "mail.corporate.com" \
--smtp-port 587 \
--imap-host "mail.corporate.com" \
--imap-port 993 \
--name "Corporate User"
# Output:
📝 Custom provider settings:
SMTP Host: mail.corporate.com
SMTP Port: 587
IMAP Host: mail.corporate.com
IMAP Port: 993
```
### Progress Indicators
EmailOS shows detailed progress during MX record lookups:
```bash
mailos configure --email "user@example.com" --validate-only
# Output with progress:
🔍 Looking up MX records for customdomain.com... ✅ Found 2 MX record(s)
📊 Analyzing MX records... ✅ Gmail detected
✓ Auto-detected provider: Gmail (via MX record)
```
## Enhanced App Password Setup
EmailOS automatically provides provider-specific app password instructions and secure input prompts during configuration.
### Automatic Setup Flow
When configuring a new account, EmailOS will:
1. **Detect your provider** (via domain or MX records)
2. **Show tailored instructions** for your specific email service
3. **Provide direct links** to app password setup pages
4. **Prompt securely** for password input (hidden from display)
### Example Setup Flow
```bash
mailos configure --email "user@gmail.com" --name "Your Name"
# Output:
✓ Auto-detected provider: Gmail (via domain)
📧 Setting up Gmail account: user@gmail.com
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔐 Gmail requires an app-specific password (not your regular password)
You need to enable 2-factor authentication and create an app password
📄 Instructions: https://myaccount.google.com/apppasswords
Enter your Gmail app password: [secure input]
```
## App Password Instructions
Provider-specific setup instructions are automatically displayed:
### Gmail
1. Enable 2-factor authentication
2. Go to Google Account settings
3. Security → 2-Step Verification → App passwords
4. Generate password for "Mail"
### Outlook/Hotmail
1. Enable two-step verification
2. Go to Security settings
3. Advanced security → Create app password
### Yahoo
1. Enable two-step verification
2. Account Security → Generate app password
3. Select "Other App" and name it
### iCloud
1. Enable two-factor authentication
2. Sign in to Apple ID
3. Security → App-Specific Passwords
4. Generate password
## Configuration File Structure
```json
{
"provider": "gmail",
"email": "user@gmail.com",
"password": "app-specific-password",
"from_name": "Display Name",
"from_email": "sender@example.com",
"profile_image": "/absolute/path/to/image.jpg",
"default_ai_cli": "claude-code",
"license_key": "optional-license"
}
```
### Profile Image Configuration
The `profile_image` field allows you to include a profile picture in your emails:
* **Supported Formats**: PNG, JPG/JPEG, GIF, WebP
* **Path Type**: Absolute path to the image file
* **Email Embedding**: Image is embedded as base64 in HTML emails
* **Template Support**: Use `{{PROFILE_IMAGE}}` placeholder in custom templates
* **Display**: Appears as a circular profile photo (150px max width)
Example usage:
```bash
# During setup
mailos configure
# When prompted, enter: /Users/john/Pictures/profile.jpg
# Or directly via command line
mailos configure --image /Users/john/Pictures/profile.jpg
# For project-specific profile image
mailos configure --local --image ./assets/team-logo.png
```
## Security Best Practices
1. **Never commit credentials**: Local configs are auto-added to `.gitignore`
2. **Use app passwords**: Never use your main account password
3. **File permissions**: Config files are created with 600 permissions
4. **Encrypted storage**: Consider using encrypted filesystems
5. **Regular rotation**: Update app passwords periodically
## Environment Variables Configuration
EmailOS supports reading email passwords from environment variables instead of storing them directly in the JSON configuration files. This provides enhanced security by keeping sensitive credentials separate from configuration files.
### Password Loading Priority
When loading configuration, EmailOS checks for passwords in this order:
1. Password field in JSON config (if present)
2. Environment variables from `.env` files
3. System environment variables
### Supported Environment Variables
All EmailOS environment variables use the `MAILOS_` prefix for clear identification and namespace separation.
#### Core Configuration Variables
* `MAILOS_APP_PASSWORD`: Default password used for all accounts when specific passwords aren't set
* `MAILOS_LICENSE_KEY`: EmailOS Pro license key for advanced features
* `MAILOS_API_KEY`: API key for external service integrations
#### Account-Specific Passwords
* `MAILOS_EMAIL_PASSWORD_`: Password for a specific email account
* Email addresses are converted to uppercase with `@` and `.` replaced by `_`
* Examples:
* `MAILOS_EMAIL_PASSWORD_USER_COMPANY_COM` for `user@company.com`
* `MAILOS_EMAIL_PASSWORD_JOHN_EXAMPLE_COM` for `user@gmail.com`
#### Backward Compatibility
For backward compatibility, the following non-prefixed variables are still supported but deprecated:
* `APP_PASSWORD` (use `MAILOS_APP_PASSWORD` instead)
* `EMAIL_PASSWORD_` (use `MAILOS_EMAIL_PASSWORD_` instead)
### Environment File Locations
EmailOS automatically resolves environment variables in this order:
1. **System environment** - Existing exported variables are read first
2. **Local**: `./.env.mailos` - Repo-local MailOS overrides
3. **Local**: `./.env` - Project-specific overrides
4. **Project config**: nearest parent `emailos.json` or `emailos.toml` - Commit-safe send defaults
5. **Global**: `~/.email/.env` - Shared across all projects
Most values only fill unset environment variables, so earlier sources win. For send commands, `from_address` in project config is the exception: it overrides `MAILOS_FROM_EMAIL` so a project can enforce its outgoing sender.
`MAILOS_FROM_NAME` is supported as the preferred env alias for the sender display name, with `MAILOS_NAME` still accepted for compatibility.
`mailos config --env-*` and `mailos config --set-*` still write to `./.env`.
### Resolved Send Values
To see the values MailOS will use for `mailos send` from the current directory, run:
```bash
mailos whoami
mailos config --values
```
The output includes source information, for example:
```text
Project Config: /path/to/emailos.toml
From Email: team@example.com
From Email Source: emailos.toml from_address (/path/to/emailos.toml)
Email: user@example.com
Email Source: emailos.toml email_address/from_address (/path/to/emailos.toml)
Local Storage: (not set)
Effective From: team@example.com
```
`mailos whoami` is the top-level shortcut for the same resolved identity report. This is the preferred check when working in nested project folders because MailOS walks upward to find `emailos.json` or `emailos.toml`.
### `mailos env` and AI Clients
`mailos env` shows the resolved non-secret send variables, the nearest parent project config source when present, and the sender policy reminder that `MAILOS_FROM_EMAIL` controls the outgoing `From` address while `--account` selects credentials.
Use named global profiles to reuse project send defaults across folders:
```bash
mailos env --save-profile work
mailos env list
mailos env work
```
Profiles are stored as `~/.email/configs/.toml`; applying a profile writes `./emailos.toml`.
By default the generated `emailos.toml` is added to the current repository's local `.git/info/exclude`; pass `--no-exclude` to leave Git excludes unchanged.
Flags:
| Flag | Type | Description | Example |
|------|------|-------------|---------|
| `--set-email` | string | Set `MAILOS_EMAIL_ADDRESS` in local `./.env` | `mailos env --set-email user@example.com` |
| `--set-from-email` | string | Set `MAILOS_FROM_EMAIL` in local `./.env` | `mailos env --set-from-email sender@example.com` |
| `--set-signature` | string | Set `MAILOS_SIGNATURE` in local `./.env` | `mailos env --set-signature "Regards"` |
| `--set-password` | string | Set `MAILOS_APP_PASSWORD` in local `./.env` | `mailos env --set-password app-password` |
| `--set-license` | string | Set `MAILOS_LICENSE_KEY` in local `./.env` | `mailos env --set-license license-key` |
| `--set-picture` | string | Set `MAILOS_PICTURE` in local `./.env` | `mailos env --set-picture /path/to/me.jpg` |
| `--show-local` | bool | Show local `./.env` contents | `mailos env --show-local` |
| `--show-global` | bool | Show global `~/.email/.env` contents | `mailos env --show-global` |
| `--edit-local` | bool | Print commands for editing local `./.env` | `mailos env --edit-local` |
| `--edit-global` | bool | Print commands for editing global `~/.email/.env` | `mailos env --edit-global` |
| `--list` | bool | List resolved MailOS environment variables | `mailos env --list` |
| `--export` | bool | Print resolved non-secret send values as shell exports | `mailos env --export` |
| `--save-profile` | string | Save nearest project config as `~/.email/configs/.toml` | `mailos env --save-profile work` |
| `--list-profiles` | bool | List global project config profiles | `mailos env list` |
| `--no-exclude` | bool | Do not add generated `emailos.toml` to local `.git/info/exclude` | `mailos env work --no-exclude` |
Some AI clients and wrapper shells only see real process environment variables, so they can miss values resolved from a parent project config. Export the resolved values before invoking those tools:
```bash
eval "$(mailos env --export)"
```
`mailos env --export` only emits non-secret send values such as `MAILOS_EMAIL_ADDRESS`, `MAILOS_FROM_EMAIL`, `MAILOS_FROM_NAME`, `MAILOS_SIGNATURE`, `MAILOS_PICTURE`, and `MAILOS_MEDIA`. It does not emit `MAILOS_APP_PASSWORD` or other credentials.
#### Global .env File (`~/.email/.env`)
Create a global environment file for system-wide password management:
```bash
# EmailOS Global Environment Variables
# This file stores sensitive configuration like passwords
# It should be excluded from version control
# Global app password for all accounts (if not specified individually)
MAILOS_APP_PASSWORD=your_app_password_here
# EmailOS Pro license key for advanced features
MAILOS_LICENSE_KEY=your_license_key_here
# API key for external service integrations
MAILOS_API_KEY=your_api_key_here
# Account-specific passwords (optional)
# Format: MAILOS_EMAIL_PASSWORD_
MAILOS_EMAIL_PASSWORD_USER_COMPANY_COM=different_password_here
MAILOS_EMAIL_PASSWORD_JOHN_EXAMPLE_COM=another_password_here
# Other environment variables
FROM_EMAIL=user@company.com
TO_EMAIL=recipient@example.com
```
#### Local Env Files (`./.env.mailos` or `./.env`)
For project-specific configurations:
```bash
# Preferred MailOS-specific local file: ./.env.mailos
MAILOS_FROM_NAME="Your Name"
MAILOS_EMAIL_ADDRESS=your-configured-account@example.com
# Or use the existing generic local file: ./.env
MAILOS_APP_PASSWORD=project_specific_password
MAILOS_LICENSE_KEY=project_license_key
# Test email addresses
FROM_EMAIL=your-configured-account@example.com
TO_EMAIL=test-recipient@example.com
```
### Configuration Migration to Environment Variables
#### Step 1: Create Environment File
Create `~/.email/.env` with your credentials:
```bash
echo "MAILOS_APP_PASSWORD=your_app_password_here" > ~/.email/.env
echo "MAILOS_LICENSE_KEY=your_license_key_here" >> ~/.email/.env
chmod 600 ~/.email/.env # Secure the file
```
#### Step 2: Remove Sensitive Data from JSON
Edit your `~/.email/config.json` to remove password and license key fields:
**Before:**
```json
{
"provider": "fastmail",
"email": "user@gmail.com",
"password": "your_app_password_here",
"from_name": "Your Name",
"license_key": "your_license_key_here",
"accounts": [
{
"email": "user@company.com",
"provider": "fastmail",
"password": "your_app_password_here",
"from_name": "Your Display Name"
}
]
}
```
**After:**
```json
{
"provider": "fastmail",
"email": "user@gmail.com",
"from_name": "Your Name",
"accounts": [
{
"email": "user@company.com",
"provider": "fastmail",
"from_name": "Your Display Name"
}
]
}
```
#### Step 3: Test Configuration
Verify that passwords and license keys are loaded correctly:
```bash
mailos send --to test@example.com --subject "Test" --body "Testing env vars" --dry-run
```
### Environment Variables Security Benefits
1. **Separation of Concerns**: Passwords are kept separate from configuration
2. **Version Control Safe**: Configuration files can be committed without exposing credentials
3. **Environment-Specific**: Different passwords for development, staging, and production
4. **File Permissions**: Local env files can have restrictive permissions (600)
### Environment File Permissions
Ensure your environment files are properly secured:
```bash
chmod 600 ~/.email/.env
chmod 600 ./.env.mailos
chmod 600 ./.env
```
### Environment Variables Troubleshooting
#### Password Not Loading
1. Check if `./.env.mailos`, `./.env`, or `~/.email/.env` exists and is readable
2. Verify environment variable names match expected format
3. Ensure no extra spaces around variable names and values
4. Check file permissions (should be readable by your user)
#### Multiple Account Issues
1. Use account-specific environment variables for different passwords
2. Verify email address conversion to environment variable name
3. Check that `APP_PASSWORD` is set as fallback
#### Environment Variable Priority
Environment variables are resolved in this order:
1. Existing system or command-prefixed environment variables
2. Local `.env.mailos` file (`./.env.mailos`)
3. Local `.env` file (`./.env`)
4. Nearest parent `emailos.json` or `emailos.toml` send defaults
5. Global `.env` file (`~/.email/.env`)
### Environment Variables Example Configurations
#### Single Account Setup
```bash
# ~/.email/.env
MAILOS_APP_PASSWORD=your_fastmail_app_password
MAILOS_LICENSE_KEY=your_license_key_here
```
#### Multiple Account Setup
```bash
# ~/.email/.env
# Default password for most accounts
MAILOS_APP_PASSWORD=default_app_password
# EmailOS Pro license key
MAILOS_LICENSE_KEY=your_license_key_here
# Specific password for work account
MAILOS_EMAIL_PASSWORD_WORK_COMPANY_COM=work_specific_password
# Specific password for personal Gmail
MAILOS_EMAIL_PASSWORD_PERSONAL_GMAIL_COM=gmail_app_password
```
#### Development Setup
```bash
# ./.env (in project directory)
MAILOS_APP_PASSWORD=dev_test_password
MAILOS_LICENSE_KEY=dev_license_key
FROM_EMAIL=dev@test.com
TO_EMAIL=test@example.com
DEBUG=true
```
### Environment Variables Best Practices
1. **Never commit `.env` files** to version control
2. **Use specific passwords** for production environments
3. **Set restrictive file permissions** (600) on environment files
4. **Use different passwords** for different environments
5. **Regularly rotate passwords** and update environment files
6. **Document required environment variables** for your team
### Integration with CI/CD
For automated environments, set environment variables directly:
```bash
export MAILOS_APP_PASSWORD=ci_password
export MAILOS_LICENSE_KEY=ci_license_key
mailos send --to alerts@company.com --subject "Build Complete" --body "Build #123 completed successfully"
```
## Multiple Accounts
EmailOS supports multiple account management through both global configuration and local aliases:
### 1. Global Account Setup
Set up your primary accounts globally:
```bash
# Set up primary account
mailos configure --email primary@company.com
# Add additional accounts to global config
mailos accounts add secondary@company.com
```
### 2. Project-Specific Aliases (New Feature)
Use existing accounts with project-specific identities:
```bash
# Create aliases that inherit authentication from global accounts
cd ~/projects/client-work
mailos configure --local --email primary@company.com --name "Client Consultant"
cd ~/projects/internal
mailos configure --local --email primary@company.com --name "Internal Team"
# Different email from global accounts
cd ~/projects/support
mailos configure --local --email secondary@company.com --name "Support Team"
```
### 3. Mixed Account Strategy
Combine global and local configurations for different needs:
```bash
# Global: Main work email
mailos configure --email john@company.com
# Project A: Use work email with project-specific branding
cd ~/projects/project-a
mailos configure --local --email john@company.com --name "Project A Lead"
# Project B: Use different company email
cd ~/projects/project-b
mailos configure --local --email team@company.com --name "Project B Team"
# Project C: Completely separate account (requires full setup)
cd ~/projects/client-external
mailos configure --local --email external@client.com --name "External Consultant"
```
### Account Configuration Hierarchy
| Configuration Type | Authentication Source | Use Case | Setup Complexity |
|-------------------|----------------------|----------|------------------|
| **Global Accounts** | Self-contained | Default for all projects | Full setup required |
| **Local Aliases** | Inherit from global | Project-specific identity | Instant setup |
| **Local Full Config** | Self-contained | Separate email account | Full setup required |
### Benefits of the New Alias System
1. **Instant Setup**: No need to re-enter passwords for existing accounts
2. **Secure**: No sensitive data stored in project directories
3. **Flexible Branding**: Different display names per project
4. **Easy Switching**: Quick setup for different project identities
For detailed account management, see `mailos help accounts`.
## Troubleshooting
### Authentication Failed
* Verify app password is correct
* Check 2FA is enabled
* Ensure IMAP/SMTP access is enabled
* Try regenerating app password
### Local Config Not Working
* Ensure you're in the correct directory
* Check `.email/config.json` exists
* Verify JSON syntax is valid
* Check file permissions (should be 600)
### Provider Not Working
* Verify IMAP/SMTP settings are correct
* Check firewall/antivirus settings
* Some providers need "less secure apps" enabled
* Corporate accounts may have restrictions
### Inheritance Issues
* Local config only overrides specified fields
* Password cannot be inherited for security
* Run `mailos info` to see active configuration
## Advanced Configuration
### Custom Email Templates with Profile Images
When using custom email templates (via `mailos template`), you can include your profile image:
```html
{{PROFILE_IMAGE}}
{{FROM_NAME}}
{{BODY}}
```
The `{{PROFILE_IMAGE}}` placeholder will be replaced with your profile image embedded as base64 data.
### Custom SMTP/IMAP Settings
For providers not listed, use custom configuration:
```bash
mailos configure --provider custom
# You'll be prompted for:
# - SMTP Host
# - SMTP Port
# - IMAP Host
# - IMAP Port
# - TLS/SSL settings
```
### Additional Environment Variables
In addition to password environment variables (see [Environment Variables Configuration](#environment-variables-configuration)), you can override configuration with:
* `MAILOS_EMAIL`: Override email address
* `MAILOS_PROVIDER`: Override provider
* `MAILOS_AI_CLI`: Override AI provider
### Validation
Configuration is validated for:
* Valid email format
* Known provider settings
* Required fields present
* Password strength (warning only)
## See Also
* `mailos setup` - Initial setup wizard
* `mailos info` - Display current configuration
* `mailos local` - Create local configuration
* `mailos provider` - Configure AI provider
```
## Integration with Email System
### Automatic Template Application
Templates are automatically applied when:
* Sending emails with `mailos send` command
* Email body contains markdown or HTML content
* Template file exists for the specified name (default: "default")
### Template Bypass
Templates are bypassed when:
* Using `--plain` flag with send commands
* No template file exists
* Template loading fails
## Template Management Commands
### List All Templates
```bash
mailos template
# Choose option 3: List templates
```
Shows all available templates with their file paths.
### Preview Template
```bash
mailos template
# Choose option 2: Preview existing template
```
Opens template in browser with sample content for visual testing.
### Edit Existing Template
```bash
mailos template --name existing-template
# Choose option 1: Create/Edit template
```
Loads existing template for modification or creates new one if it doesn't exist.
## Best Practices
### Email Client Compatibility
* Use inline CSS for maximum compatibility
* Avoid JavaScript (not supported by most email clients)
* Test with multiple email clients (Gmail, Outlook, Apple Mail)
* Use table layouts for complex designs if needed
### Performance and Size
* Keep total email size under 100KB
* Optimize images before base64 encoding
* Minimize CSS to reduce file size
* Avoid external dependencies
### Accessibility
* Include alt text for images
* Use semantic HTML structure
* Ensure sufficient color contrast
* Test with screen readers
### Mobile Optimization
* Use responsive design principles
* Test on mobile devices
* Ensure readable font sizes
* Make tap targets large enough
## Troubleshooting
### Template Not Applied
* Verify template file exists at expected location
* Check that template contains `{{BODY}}` placeholder
* Ensure not using `--plain` flag when sending
* Validate HTML syntax
### Images Not Showing
* Check that profile image file exists and is readable
* Verify image format is supported (JPG, PNG, GIF, WEBP)
* Ensure image file size is reasonable (under 1MB recommended)
### Browser Preview Issues
* Check that default browser is configured
* Verify template file permissions
* Test opening file manually in browser
### Template Saving Issues
* Ensure directory permissions allow file creation
* Check available disk space
* Verify file path is valid and accessible
## Examples
### Creating Company Template
```bash
mailos template --name company
# Paste your company HTML template
# Type "END" when finished
# Preview if desired
# Confirm save
```
### Quick Browser Preview
```bash
mailos template --open-browser
```
### Remove Old Template
```bash
mailos template --remove --name old-template
```
### List Available Templates
```bash
mailos template
# Choose option 3
```
## File Locations
Templates are stored in these locations based on your configuration:
* **Local Project**: `.email/templates/[name].html` (if `.email` directory exists)
* **Global User**: `~/.email/templates/[name].html` (default location)
The system automatically creates the necessary directories when saving templates.
---
---
url: /scheduled-sending.md
---
# EmailOS Scheduled Email Sending
Send emails at a future time using EmailOS's built-in scheduler. Schedule emails with simple commands and let the watch daemon handle sending them at the right time.
## Quick Start
```bash
# Schedule an email for 2 hours from now
mailos send --to user@example.com \
--subject "Meeting Reminder" \
--body "Don't forget our 3pm meeting" \
--schedule-in 2h
# Start the scheduler to send scheduled emails
mailos watch
```
## How It Works
1. **Schedule emails** using `--schedule-at` or `--schedule-in` flags with the `send` command
2. **Start the scheduler** with `mailos watch` in a dedicated terminal or background process
3. **Emails are sent automatically** at their scheduled time
4. **Sent emails are archived** to `~/.email/sent-scheduled/`
## Scheduling Commands
### Schedule Using Relative Time (`--schedule-in`)
Schedule emails relative to the current time using Go duration format:
```bash
# 30 minutes from now
mailos send --to client@example.com \
--subject "Follow-up" \
--body "Checking in on the proposal" \
--schedule-in 30m
# 2 hours from now
mailos send --to team@company.com \
--subject "Daily Update" \
--body "Here's today's progress report" \
--schedule-in 2h
# 24 hours (tomorrow at this time)
mailos send --to boss@company.com \
--subject "Weekly Report" \
--body "This week's accomplishments..." \
--schedule-in 24h
# 1 hour 30 minutes from now
mailos send --to vendor@example.com \
--subject "Contract Review" \
--body "Please review the attached contract" \
--schedule-in 1h30m
```
#### Supported Duration Units
* `s` - seconds (e.g., `30s`)
* `m` - minutes (e.g., `15m`)
* `h` - hours (e.g., `2h`)
* Combinations (e.g., `1h30m`, `2h15m30s`)
### Schedule Using Absolute Time (`--schedule-at`)
Schedule emails for a specific date and time using RFC3339 format:
```bash
# Specific date and time (UTC)
mailos send --to user@example.com \
--subject "Quarterly Review" \
--body "Q4 results are ready for review" \
--schedule-at "2026-01-28T09:00:00Z"
# Specific date and time (with timezone)
mailos send --to client@example.com \
--subject "Project Launch" \
--body "The new feature goes live today!" \
--schedule-at "2026-02-01T15:00:00-05:00"
# ISO8601 format (without timezone assumes local time)
mailos send --to team@company.com \
--subject "Meeting Reminder" \
--body "Stand-up meeting in 1 hour" \
--schedule-at "2026-01-28T10:30:00"
```
#### Time Format Requirements
* RFC3339: `2006-01-02T15:04:05Z` (UTC)
* RFC3339 with timezone: `2006-01-02T15:04:05-07:00`
* ISO8601: `2006-01-02T15:04:05` (local time)
**Note:** Scheduled time must be in the future. Past times will result in an error.
## Managing Scheduled Emails
### List Scheduled Emails
View all pending scheduled emails:
```bash
mailos schedule-list
```
Example output:
```
📬 Scheduled Emails (3)
1. ⏰ Pending
ID: 1769539111027403000
To: [client@example.com]
Subject: Follow-up Meeting
Scheduled: 2026-01-28 14:30:00 (in 2h 15m)
Created: 2026-01-28 12:15:00
2. ⏰ Pending
ID: 1769539212027403001
To: [team@company.com]
Subject: Daily Update
Scheduled: 2026-01-28 17:00:00 (in 4h 45m)
Created: 2026-01-28 12:15:00
3. ⚡ Due now
ID: 1769539313027403002
To: [boss@company.com]
Subject: Urgent Report
Scheduled: 2026-01-28 12:00:00
Created: 2026-01-28 11:55:00
💡 Run 'mailos watch' to start the scheduler
```
### Watch Command - The Scheduler Daemon
The `watch` command monitors scheduled emails and sends them at the right time:
```bash
# Start watching with default 1-minute interval
mailos watch
# Check every 30 seconds (more responsive)
mailos watch --interval 30s
# Check every 5 minutes (lower resource usage)
mailos watch --interval 5m
# Show detailed output (useful for debugging)
mailos watch --verbose
# Process due emails once and exit (useful for cron jobs)
mailos watch --once
```
#### Watch Command 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: Follow-up Meeting → [client@example.com]
```
### Watch Command Flags
| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--interval` | duration | 1m0s | Check interval (e.g., 30s, 1m, 5m) |
| `--once` | bool | false | Process due emails once and exit |
| `--verbose` | bool | false | Show detailed output including SMTP debug info |
## Storage Locations
Scheduled emails are stored in JSON format in your home directory:
* **Pending emails**: `~/.email/scheduled-emails/`
* **Sent archive**: `~/.email/sent-scheduled/`
### File Format
Each scheduled email is stored as a JSON file:
```
~/.email/scheduled-emails/20260128_143000_1769539111027403000.json
```
Filename format: `{scheduled_time}_{email_id}.json`
## Workflow Examples
### Simple Daily Reminder
Schedule a daily reminder at 9 AM:
```bash
# Calculate time until 9 AM tomorrow
mailos send --to yourself@example.com \
--subject "Daily Task Reminder" \
--body "Don't forget to review the project board" \
--schedule-at "2026-01-29T09:00:00Z"
```
### Batch Scheduling
Schedule multiple emails at once:
```bash
# Morning follow-up
mailos send --to client1@example.com \
--subject "Project Update" \
--body "..." \
--schedule-in 2h
# Afternoon check-in
mailos send --to client2@example.com \
--subject "Status Check" \
--body "..." \
--schedule-in 6h
# Evening summary
mailos send --to team@company.com \
--subject "Daily Summary" \
--body "..." \
--schedule-in 10h
# Start the scheduler
mailos watch
```
### Background Scheduler
Run the scheduler as a background process:
```bash
# Using nohup (output to log file)
nohup mailos watch --interval 30s > ~/mailos-scheduler.log 2>&1 &
# Using disown (bash/zsh)
mailos watch --interval 30s &
disown
# Check if scheduler is running
ps aux | grep "mailos watch"
# Stop the scheduler
pkill -f "mailos watch"
```
### Cron Integration
Use `watch --once` in a cron job for scheduled checks:
```bash
# Add to crontab: crontab -e
# Check every 5 minutes
*/5 * * * * /usr/local/bin/mailos watch --once >> ~/mailos-cron.log 2>&1
# Check every hour at :00
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 Terminal Launch
Add to your shell startup file (`~/.zshrc` or `~/.bashrc`):
```bash
# Start scheduler silently in background on terminal launch
if ! pgrep -f "mailos watch" > /dev/null; then
nohup mailos watch --interval 30s > /dev/null 2>&1 &
fi
```
## Advanced Usage
### Scheduling with All Send Features
Combine scheduling with other send command features:
```bash
# Schedule email with attachments
mailos send --to client@example.com \
--subject "Proposal Document" \
--body "Please review the attached proposal" \
--attach ~/Documents/proposal.pdf \
--schedule-in 3h
# Schedule with CC and BCC
mailos send --to lead@example.com \
--cc manager@company.com \
--bcc compliance@company.com \
--subject "Contract Agreement" \
--body "Please review and sign" \
--schedule-at "2026-01-29T10:00:00Z"
# Schedule with custom signature
mailos send --to vendor@example.com \
--subject "Purchase Order" \
--body "Attached is the PO for review" \
--signature "Best regards,\nProcurement Team" \
--schedule-in 24h
# Schedule markdown email with template
mailos send --to newsletter@company.com \
--subject "Monthly Newsletter" \
--file newsletter.md \
--template \
--schedule-at "2026-02-01T08:00:00Z"
```
### Account-Specific Scheduling
Schedule emails from specific accounts:
```bash
# From work account
mailos send --account work@company.com \
--to client@example.com \
--subject "Work Update" \
--body "..." \
--schedule-in 2h
# From personal account
mailos send --account personal@gmail.com \
--to friend@example.com \
--subject "Catch up" \
--body "..." \
--schedule-at "2026-01-29T18:00:00Z"
```
## Troubleshooting
### Email Not Sent at Scheduled Time
**Problem**: Email remains in scheduled queue past its scheduled time.
**Solution**:
1. Check if `mailos watch` is running: `ps aux | grep "mailos watch"`
2. Verify no errors in watch output: `mailos watch --verbose`
3. Check system time is correct: `date`
4. Manually process due emails: `mailos watch --once`
### Watch Command Not Finding Due Emails
**Problem**: Watch command reports "No emails due" when emails should be sent.
**Solution**:
1. List scheduled emails: `mailos schedule-list`
2. Verify scheduled time is in the past
3. Check file permissions: `ls -la ~/.email/scheduled-emails/`
4. Run watch with verbose flag: `mailos watch --once --verbose`
### Cannot Schedule Past Times
**Problem**: Error: "scheduled time must be in the future"
**Solution**:
* Verify your system time is correct: `date`
* For `--schedule-at`, ensure timezone is specified correctly
* For `--schedule-in`, use positive durations only
### Scheduler High Resource Usage
**Problem**: Watch command using too much CPU or memory.
**Solution**:
* Increase check interval: `mailos watch --interval 5m` (instead of default 1m)
* Use cron with `--once` instead of continuous watch
* Check for orphaned watch processes: `pkill -f "mailos watch"`
### Email Sent But Still in Queue
**Problem**: Email was sent but still appears in `mailos schedule-list`.
**Solution**:
* Check sent-scheduled folder: `ls ~/.email/sent-scheduled/`
* Manually remove from queue: `rm ~/.email/scheduled-emails/{email_file}.json`
* Restart watch command
## Integration Examples
### With Email Groups
Schedule bulk emails to groups:
```bash
# Schedule to email group
mailos send --group team-leads \
--subject "Leadership Meeting" \
--body "Agenda attached" \
--schedule-at "2026-01-29T14:00:00Z"
```
### With Natural Language
Combine with natural language parsing:
```bash
# Natural language will be parsed, then scheduled
mailos send "remind the team about tomorrow's meeting" --schedule-in 12h
```
### Preview Before Scheduling
Preview the email before scheduling:
```bash
# Preview the email (won't schedule)
mailos send --to user@example.com \
--subject "Test" \
--body "Preview content" \
--preview
# Then schedule if satisfied
mailos send --to user@example.com \
--subject "Test" \
--body "Preview content" \
--schedule-in 1h
```
## Best Practices
1. **Keep watch running**: Use background process or cron for reliable sending
2. **Use relative times** for near-future emails (easier than calculating exact times)
3. **Use absolute times** for emails that must go at specific times (e.g., 9 AM daily)
4. **Check scheduler logs**: Use `--verbose` to debug timing issues
5. **Set appropriate intervals**: 1 minute for time-sensitive, 5 minutes for general use
6. **Monitor sent folder**: Review `~/.email/sent-scheduled/` periodically
7. **Test with short durations**: Use `--schedule-in 1m` to test your setup
8. **Archive old scheduled emails**: Clean up `~/.email/sent-scheduled/` monthly
## Related Commands
* [`mailos send`](send.md) - Main email sending command with all flags
* `mailos schedule-list` - List all scheduled emails
* `mailos watch` - Scheduler daemon to send scheduled emails
## Files and Directories
| Path | Purpose |
|------|---------|
| `~/.email/scheduled-emails/` | Pending scheduled emails (JSON format) |
| `~/.email/sent-scheduled/` | Archive of sent scheduled emails |
| `~/.email/.email/config.json` | Account configuration used by scheduler |
## Technical Details
### Email Message Structure
Each scheduled email is stored with complete metadata:
```json
{
"id": "1769539111027403000",
"scheduled_at": "2026-01-28T14:30:00Z",
"message": {
"to": ["client@example.com"],
"cc": [],
"bcc": [],
"subject": "Follow-up Meeting",
"body": "Let's discuss the project status",
"attachments": [],
"include_signature": true
},
"account_email": "andrew@email-os.com",
"created_at": "2026-01-28T12:15:00Z"
}
```
### Scheduling Algorithm
1. Email is saved to `~/.email/scheduled-emails/` with timestamp in filename
2. Watch command checks directory every interval (default: 1 minute)
3. Compares `scheduled_at` time with current time
4. Sends email if `scheduled_at <= current_time`
5. Moves sent email to `~/.email/sent-scheduled/`
6. Removes from scheduled queue
### Time Precision
* Check interval determines precision (default: 1 minute)
* Emails sent within 1 minute of scheduled time (or your custom interval)
* For more precise timing, use shorter intervals: `--interval 10s`
## See Also
* [Send Command Documentation](send.md) - Complete send command reference
* [Draft Management](drafts.md) - Managing email drafts
* [Configuration](configure.md) - Setting up accounts
---
---
url: /scheduled.md
---
# Scheduled Command
The scheduled email system stores queued emails and sends them when due.
Use these commands:
```bash
mailos schedule-list
mailos watch
```
`schedule-list` shows queued emails and `watch` continuously processes due emails.
---
---
url: /watch.md
---
# EmailOS Watch Command Documentation
The `mailos watch` command monitors scheduled emails and automatically sends them at their scheduled time.
## Quick Start
```bash
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:
```bash
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 → [team@company.com]
```
### Custom Check Interval
Check more frequently for time-sensitive emails:
```bash
mailos watch --interval 30s
```
Or check less frequently to save resources:
```bash
mailos watch --interval 5m
```
### One-Time Processing
Process all due emails once and exit (useful for cron jobs):
```bash
mailos watch --once
```
### Verbose Mode
See detailed SMTP debugging information:
```bash
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:
```bash
nohup mailos watch --interval 30s > ~/mailos-scheduler.log 2>&1 &
```
Check if running:
```bash
ps aux | grep "mailos watch"
```
Stop the scheduler:
```bash
pkill -f "mailos watch"
```
### Using screen or tmux
Run in a persistent terminal session:
```bash
# 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`:
```ini
[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:
```bash
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:
```bash
# 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