Email OS Docs

Appearance

Installation Guide ​

Email OS is distributed as a native Go CLI. The recommended installers download the signed release binary for your platform instead of requiring Node.js or npm.

Quick Install ​

Direct Install (macOS, Linux, WSL) ​

bash
curl -fsSL https://email-os.com/install.sh | bash

The installer downloads the matching GitHub Release archive, verifies the release checksum when available, and installs mailos into ~/.local/bin by default.

To install somewhere else:

bash
curl -fsSL https://email-os.com/install.sh | MAILOS_INSTALL_DIR=/usr/local/bin bash

Package Managers ​

Homebrew (macOS/Linux) ​

bash
brew install email-os/tap/mailos

Optional npm Compatibility Package ​

The npm package is a secondary compatibility channel. Prefer the direct installer or Homebrew for the core CLI.

bash
npm install -g mailos

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 install email-os/tap/mailos

# Arch Linux
paru -S mailos-bin

Platform-Specific Installation ​

macOS ​

Apple Silicon (M1/M2/M3/M4) ​

bash
curl -L https://email-os.com/releases/latest/mailos-darwin-arm64.tar.gz | tar xz
sudo mv mailos /usr/local/bin/

Intel Macs ​

bash
curl -L https://email-os.com/releases/latest/mailos-darwin-amd64.tar.gz | tar xz
sudo mv mailos /usr/local/bin/

Linux ​

x64/AMD64 ​

bash
curl -L https://email-os.com/releases/latest/mailos-linux-amd64.tar.gz | tar xz
sudo mv mailos /usr/local/bin/

ARM64 ​

bash
curl -L https://email-os.com/releases/latest/mailos-linux-arm64.tar.gz | tar xz
sudo mv mailos /usr/local/bin/

Windows ​

Using PowerShell ​

powershell
# Download the binary
Invoke-WebRequest -Uri "https://email-os.com/releases/latest/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://email-os.com/releases/latest/mailos-linux-amd64.tar.gz | tar xz
sudo mv mailos /usr/local/bin/

Build from Source ​

Prerequisites ​

  • Go 1.25 or higher
  • Git

Build Steps ​

bash
# Clone the repository
git clone https://github.com/email-os/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 - Configure your email account with app passwords
  2. Documentation Index - 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 ​

Re-run the installer to get the latest version:

bash
curl -fsSL https://email-os.com/install.sh | bash

With Homebrew:

bash
brew upgrade mailos

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.

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:

bash
# If mailos command is still available
mailos cleanup

# If you get "command not found", manually download and run:
curl -fsSL https://email-os.com/install.sh | bash
export PATH="$HOME/.local/bin:$PATH"
mailos cleanup

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
curl -fsSL https://email-os.com/install.sh | bash

# 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
curl -fsSL https://email-os.com/install.sh | bash

# Complete the uninstallation
mailos uninstall --force

# Remove the binary again
rm -f "$HOME/.local/bin/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 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.

Installer Download Issues ​

If the direct installer fails:

  1. Check that a release exists at https://github.com/email-os/cli/releases.
  2. Confirm your platform is supported: macOS/Linux on x64 or ARM64.
  3. Try a custom install directory:
    bash
    curl -fsSL https://email-os.com/install.sh | MAILOS_INSTALL_DIR=/usr/local/bin bash
  4. Download the matching archive manually from the latest GitHub Release.

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 ​

Next Steps ​

After installation, proceed to:

  1. Setup Guide - Configure your email account with app passwords
  2. Documentation Index - 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.

Released under the MIT License.

Copyright © Email OS