EmailOS Configure Command Documentation

The mailos configure command manages email account configuration with support for both global and local (project-specific) settings.

Basic Usage

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 [email protected]
--provider	Email provider	--provider gmail
--name	Display name for emails	--name "John Smith"
--from	From email address (sender)	--from [email protected]
--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: [email protected]
  - password: ****
  - from_name: John Smith

Local Config (./.email/):
  - from_name: Project Bot     # Overrides global
  - from_email: [email protected] # 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

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

mailos configure
# Follow interactive prompts

Create Local Configuration

mailos configure --local
# Creates .email/config.json in current directory

Direct Configuration

mailos configure \
  --email [email protected] \
  --provider gmail \
  --name "John Smith" \
  --ai claude-code

Project-Specific Sender

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

Set Email Signature

# 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

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

{
  "provider": "gmail",
  "email": "[email protected]",
  "password": "app-specific-password",
  "from_name": "Display Name",
  "from_email": "[email protected]",
  "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 placeholder in custom templates
• Display: Appears as a circular profile photo (150px max width)

Example usage:

# 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

# 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:

{
  "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:

# 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

   mailos configure --email [email protected]

2. Project Override: Use different account per project

   cd project1
   mailos configure --local --email [email protected]
   
   cd ../project2
   mailos configure --local --email [email protected]

3. Adding Aliases/Sub-emails: Add additional email addresses from the same provider

   mailos accounts --set [email protected]
   # 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:

<!-- 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:

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:

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:

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