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	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: [email protected]
  - password: ****
  - from_name: Your Name

Local Config (./.email/):
  - from_name: Project Bot     # Overrides global
  - from_email: [email protected] # Project-specific sender

Smart Provider Detection

EmailOS includes intelligent provider detection that automatically identifies your email provider using multiple methods:

Detection Methods

Domain Recognition: Direct domain matching for known providers
- @gmail.com → Gmail
- @fastmail.com → Fastmail
- @outlook.com → Outlook
- @yahoo.com → Yahoo
- @icloud.com → iCloud
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
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 "[email protected]"
# ✓ Auto-detected provider: Gmail (via domain)

# MX record detection for custom domains  
mailos configure --email "[email protected]"
# ✓ Auto-detected provider: Gmail (via MX record)

# Provider validation with mismatch warning
mailos configure --email "[email protected]" --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 "[email protected]" --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:

Provider Selection: Choose your email service
Email Address: Enter your email
App Password: Enter app-specific password
Display Name: Optional sender name
Profile Image: Optional profile image path
From Email: Optional custom sender address
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 [email protected] --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: [email protected]
# ✓ 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 [email protected] \
  --provider gmail \
  --name "Your Name" \
  --license "lic_abc123"

# Auto-detection (provider detected automatically)
mailos configure \
  --email [email protected] \
  --name "Your Name" \
  --ai claude-code

# Explicit provider with validation
mailos configure \
  --email [email protected] \
  --provider gmail \
  --name "Your Name" \
  --image /Users/john/profile.jpg

# Force overwrite existing config
mailos configure \
  --email [email protected] \
  --name "Your Name" \
  --force

Project-Specific Sender

bash

# In project directory - traditional local config
mailos configure --local \
  --from [email protected] \
  --name "Project Notifications"

# Using email alias (if exists in global config) - New Feature
mailos configure --local \
  --email [email protected] \
  --name "Project Team" \
  --from [email protected]

Update Password Only

bash

mailos configure --quick
# Select "Update Password" from menu

Advanced Examples

bash

# Complete setup with all options
mailos configure \
  --email "[email protected]" \
  --name "Company Support" \
  --from "[email protected]" \
  --image "/opt/company/logo.png" \
  --ai claude-code \
  --backup \
  --test

# Custom domain with provider detection
mailos configure --email "[email protected]"
# EmailOS will check MX records and detect the actual provider

# Local project configuration with backup
mailos configure --local \
  --name "Project Bot" \
  --from "[email protected]" \
  --backup

# Force update without prompts
mailos configure \
  --email "[email protected]" \
  --provider gmail \
  --force

# Validate configuration without saving
mailos configure \
  --email "[email protected]" \
  --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 "[email protected]" \
  --name "New Name" \
  --diff

# Test configuration with connection validation
mailos configure \
  --email "[email protected]" \
  --name "Test User" \
  --test

# Custom provider with specific ports
mailos configure \
  --email "[email protected]" \
  --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 [email protected] in your global accounts
mailos configure --local --email [email protected] --name "Project Lead"

# EmailOS detects the existing account and creates an alias:
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#               CREATE LOCAL EMAIL ALIAS                  
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# 📧 Setting up [email protected] 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": "[email protected]",
  "password": "",
  "from_name": "Project Lead",
  "from_email": "[email protected]",
  "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:

Email exists in global accounts array:

bash

# If your ~/.email/config.json has this email in accounts[]
mailos configure --local --email [email protected]

Email matches main global email:

bash

# If your main email is [email protected]
mailos configure --local --email [email protected]

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 [email protected] --name "Project Bot"
# → Creates alias, inherits authentication

# ❌ FULL SETUP (new email address) 
mailos configure --local --email [email protected] --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 [email protected] --name "Client A Consultant"

cd ~/projects/client-b  
mailos configure --local --email [email protected] --name "Client B Consultant"

2. Customize From Addresses

bash

# Use alias with custom from address
mailos configure --local \
  --email [email protected] \
  --name "Support Team" \
  --from [email protected]

3. Inherit Settings from Existing Accounts

bash

# If your global config has specific settings for [email protected],
# the alias will inherit display name and other preferences
mailos configure --local --email [email protected]

# Override inherited settings as needed
mailos configure --local \
  --email [email protected] \
  --name "Custom Project Name"

Advanced Configuration Features

Configuration Validation

Use --validate-only to test configuration without saving:

bash

mailos configure \
  --email "[email protected]" \
  --provider gmail \
  --name "Test User" \
  --validate-only

# Output:
✅ Configuration validation successful!
📋 Configuration preview:
   Email: [email protected]
   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 "[email protected]" \
  --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 "[email protected]" \
  --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 "[email protected]" \
  --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 "[email protected]" --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:

Detect your provider (via domain or MX records)
Show tailored instructions for your specific email service
Provide direct links to app password setup pages
Prompt securely for password input (hidden from display)

Example Setup Flow

bash

mailos configure --email "[email protected]" --name "Your Name"

# Output:
✓ Auto-detected provider: Gmail (via domain)

📧 Setting up Gmail account: [email protected]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔐 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

Enable 2-factor authentication
Go to Google Account settings
Security → 2-Step Verification → App passwords
Generate password for "Mail"

Outlook/Hotmail

Enable two-step verification
Go to Security settings
Advanced security → Create app password

Yahoo

Enable two-step verification
Account Security → Generate app password
Select "Other App" and name it

iCloud

Enable two-factor authentication
Sign in to Apple ID
Security → App-Specific Passwords
Generate password

Configuration File Structure

json

{
  "provider": "gmail",
  "email": "[email protected]",
  "password": "app-specific-password",
  "from_name": "Display Name",
  "from_email": "[email protected]",
  "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 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

Never commit credentials: Local configs are auto-added to .gitignore
Use app passwords: Never use your main account password
File permissions: Config files are created with 600 permissions
Encrypted storage: Consider using encrypted filesystems
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:

Password field in JSON config (if present)
Environment variables from .env files
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_<EMAIL>: Password for a specific email account
- Email addresses are converted to uppercase with @ and . replaced by _
- Examples:
  - MAILOS_EMAIL_PASSWORD_USER_COMPANY_COM for [email protected]
  - MAILOS_EMAIL_PASSWORD_JOHN_EXAMPLE_COM for [email protected]

Backward Compatibility

For backward compatibility, the following non-prefixed variables are still supported but deprecated:

APP_PASSWORD (use MAILOS_APP_PASSWORD instead)
EMAIL_PASSWORD_<EMAIL> (use MAILOS_EMAIL_PASSWORD_<EMAIL> instead)

Environment File Locations

EmailOS automatically resolves environment variables in this order:

System environment - Existing exported variables are read first
Local: ./.env.mailos - Repo-local MailOS overrides
Local: ./.env - Project-specific overrides
Project config: nearest parent emailos.json or emailos.toml - Commit-safe send defaults
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: [email protected]
From Email Source: emailos.toml from_address (/path/to/emailos.toml)
Email: [email protected]
Email Source: emailos.toml email_address/from_address (/path/to/emailos.toml)
Local Storage: (not set)
Effective From: [email protected]

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/<name>.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 [email protected]`
`--set-from-email`	string	Set `MAILOS_FROM_EMAIL` in local `./.env`	`mailos env --set-from-email [email protected]`
`--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/<name>.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_<EMAIL_WITH_UNDERSCORES>
MAILOS_EMAIL_PASSWORD_USER_COMPANY_COM=different_password_here
MAILOS_EMAIL_PASSWORD_JOHN_EXAMPLE_COM=another_password_here

# Other environment variables
FROM_EMAIL=[email protected]
TO_EMAIL=[email protected]

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

# 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=[email protected]
TO_EMAIL=[email protected]

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": "[email protected]",
  "password": "your_app_password_here",
  "from_name": "Your Name",
  "license_key": "your_license_key_here",
  "accounts": [
    {
      "email": "[email protected]",
      "provider": "fastmail",
      "password": "your_app_password_here",
      "from_name": "Your Display Name"
    }
  ]
}

After:

json

{
  "provider": "fastmail",
  "email": "[email protected]",
  "from_name": "Your Name",
  "accounts": [
    {
      "email": "[email protected]",
      "provider": "fastmail",
      "from_name": "Your Display Name"
    }
  ]
}

Step 3: Test Configuration

Verify that passwords and license keys are loaded correctly:

bash

mailos send --to [email protected] --subject "Test" --body "Testing env vars" --dry-run

Environment Variables Security Benefits

Separation of Concerns: Passwords are kept separate from configuration
Version Control Safe: Configuration files can be committed without exposing credentials
Environment-Specific: Different passwords for development, staging, and production
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

Check if ./.env.mailos, ./.env, or ~/.email/.env exists and is readable
Verify environment variable names match expected format
Ensure no extra spaces around variable names and values
Check file permissions (should be readable by your user)

Multiple Account Issues

Use account-specific environment variables for different passwords
Verify email address conversion to environment variable name
Check that APP_PASSWORD is set as fallback

Environment Variable Priority

Environment variables are resolved in this order:

Existing system or command-prefixed environment variables
Local .env.mailos file (./.env.mailos)
Local .env file (./.env)
Nearest parent emailos.json or emailos.toml send defaults
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=[email protected]
TO_EMAIL=[email protected]
DEBUG=true

Environment Variables Best Practices

Never commit .env files to version control
Use specific passwords for production environments
Set restrictive file permissions (600) on environment files
Use different passwords for different environments
Regularly rotate passwords and update environment files
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 [email protected] --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 [email protected]

# Add additional accounts to global config
mailos accounts add [email protected]

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 [email protected] --name "Client Consultant"

cd ~/projects/internal
mailos configure --local --email [email protected] --name "Internal Team"

# Different email from global accounts
cd ~/projects/support
mailos configure --local --email [email protected] --name "Support Team"

3. Mixed Account Strategy

Combine global and local configurations for different needs:

bash

# Global: Main work email
mailos configure --email [email protected]

# Project A: Use work email with project-specific branding
cd ~/projects/project-a
mailos configure --local --email [email protected] --name "Project A Lead"

# Project B: Use different company email
cd ~/projects/project-b  
mailos configure --local --email [email protected] --name "Project B Team"

# Project C: Completely separate account (requires full setup)
cd ~/projects/client-external
mailos configure --local --email [email protected] --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

Instant Setup: No need to re-enter passwords for existing accounts
Secure: No sensitive data stored in project directories
Flexible Branding: Different display names per project
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

<!-- Example template with profile image -->
<html>
  <body style="font-family: Arial, sans-serif;">
    <div style="text-align: center; padding: 20px;">
      {{PROFILE_IMAGE}}
      <h2>{{FROM_NAME}}</h2>
    </div>
    <div style="padding: 20px;">
      {{BODY}}
    </div>
  </body>
</html>

The 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), 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)

EmailOS Configure Command Documentation ​

Basic Usage ​

Command-Line Flags ​

Basic Options ​

Advanced Options ​

Configuration Types ​

Global Configuration ​

Local Configuration ​

Local Email Aliases ​

Alias vs Full Configuration ​

Configuration Inheritance ​

Smart Provider Detection ​

Detection Methods ​

Detection Examples ​

Supported Providers ​

AI CLI Providers ​

Interactive Mode ​

Quick Configuration ​

Examples ​

Initial Setup ​

Create Local Configuration ​

Create Local Email Alias (New Feature) ​

Direct Configuration ​

Project-Specific Sender ​

Update Password Only ​

Advanced Examples ​

Local Email Alias Workflow (New Feature) ​

How Email Aliases Work ​

Automatic Alias Detection ​

Alias Configuration Structure ​

When Aliases Are Created ​

Alias vs Full Setup Examples ​

Alias Management Best Practices ​

1. Use Aliases for Project-Specific Identities ​

2. Customize From Addresses ​

3. Inherit Settings from Existing Accounts ​

Advanced Configuration Features ​

Configuration Validation ​

Connection Testing ​

Configuration Export/Backup ​

Configuration Diff Preview ​

Custom Provider Setup ​

Progress Indicators ​

Enhanced App Password Setup ​

Automatic Setup Flow ​

Example Setup Flow ​

App Password Instructions ​

Gmail ​

Outlook/Hotmail ​

Yahoo ​

iCloud ​

Configuration File Structure ​

Profile Image Configuration ​

Security Best Practices ​

Environment Variables Configuration ​

Password Loading Priority ​

Supported Environment Variables ​

Core Configuration Variables ​

Account-Specific Passwords ​

Backward Compatibility ​

Environment File Locations ​

Resolved Send Values ​

mailos env and AI Clients ​

Global .env File (~/.email/.env) ​

Local Env Files (./.env.mailos or ./.env) ​

Configuration Migration to Environment Variables ​

Step 1: Create Environment File ​

Step 2: Remove Sensitive Data from JSON ​

Step 3: Test Configuration ​

Environment Variables Security Benefits ​

Environment File Permissions ​

Environment Variables Troubleshooting ​

Password Not Loading ​

Multiple Account Issues ​

Environment Variable Priority ​

Environment Variables Example Configurations ​

Single Account Setup ​

Multiple Account Setup ​

Development Setup ​

Environment Variables Best Practices ​

EmailOS Configure Command Documentation

Basic Usage

Command-Line Flags

Basic Options

Advanced Options

Configuration Types

Global Configuration

Local Configuration

Local Email Aliases

Alias vs Full Configuration

Configuration Inheritance

Smart Provider Detection

Detection Methods

Detection Examples

Supported Providers

AI CLI Providers

Interactive Mode

Quick Configuration

Examples

Initial Setup

Create Local Configuration

Create Local Email Alias (New Feature)

Direct Configuration

Project-Specific Sender

Update Password Only

Advanced Examples

Local Email Alias Workflow (New Feature)

How Email Aliases Work

Automatic Alias Detection

Alias Configuration Structure

When Aliases Are Created

Alias vs Full Setup Examples

Alias Management Best Practices

1. Use Aliases for Project-Specific Identities

2. Customize From Addresses

3. Inherit Settings from Existing Accounts

Advanced Configuration Features

Configuration Validation

Connection Testing

Configuration Export/Backup

Configuration Diff Preview

Custom Provider Setup

Progress Indicators

Enhanced App Password Setup

Automatic Setup Flow

Example Setup Flow

App Password Instructions

Gmail

Outlook/Hotmail

Yahoo

iCloud

Configuration File Structure

Profile Image Configuration

Security Best Practices

Environment Variables Configuration

Password Loading Priority

Supported Environment Variables

Core Configuration Variables

Account-Specific Passwords

Backward Compatibility

Environment File Locations

Resolved Send Values

`mailos env` and AI Clients

Global .env File (`~/.email/.env`)

Local Env Files (`./.env.mailos` or `./.env`)

Configuration Migration to Environment Variables

Step 1: Create Environment File

Step 2: Remove Sensitive Data from JSON

Step 3: Test Configuration

Environment Variables Security Benefits

Environment File Permissions

Environment Variables Troubleshooting

Password Not Loading

Multiple Account Issues

Environment Variable Priority

Environment Variables Example Configurations

Single Account Setup

Multiple Account Setup

Development Setup

Environment Variables Best Practices