Email OS Docs

Appearance

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 )
  • 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:

  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 ​

ProviderSMTP ServerSMTP PortIMAP ServerIMAP Port
Gmailsmtp.gmail.com587imap.gmail.com993
Outlooksmtp-mail.outlook.com587outlook.office365.com993
Yahoosmtp.mail.yahoo.com587imap.mail.yahoo.com993
iCloudsmtp.mail.me.com587imap.mail.me.com993

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=[email protected]
export MAILOS_PASSWORD=app-password
mailos setup

Automated Setup ​

For scripted installation:

bash
mailos setup --non-interactive \
  --provider gmail \
  --email [email protected] \
  --password "app-password"

Import Configuration ​

bash
# Copy from another machine
scp other-machine:~/.email/config.json ~/.email/
chmod 600 ~/.email/config.json

Post-Setup ​

  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 [email protected] --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 ​

Support Commands ​

bash
# Check system
mailos test

# View logs
mailos --debug

# Get version
mailos --version

Released under the MIT License.

Copyright © Email OS