mcmail

Mailcheap CLI — manage your mail server from the terminal.

Features

• 🔐 Secure authentication with token caching
• 📬 Manage email accounts (list / create / delete / info)
• 🔀 Manage aliases (list / create / delete)
• 🌐 List domains
• 📋 Table or JSON output (--json flag)
• 🔄 Auto token refresh (if password is cached)
• 🌍 Environment variable support

Installation

From npm (recommended)

npm install -g mcmail

From source

git clone https://github.com/shazhou-ww/mcmail.git
cd mcmail
npm install
npm run build
npm link

Configuration

Environment variables (highest priority)

Variable	Description
MCMAIL_HOST	API host (default: https://mail8.mymailcheap.com)
MCMAIL_USER	Username for stateless auth
MCMAIL_PASSWORD	Password for stateless auth

When MCMAIL_USER and MCMAIL_PASSWORD are set, mcmail authenticates fresh on every call and ignores the credentials file.

Credentials file

After mcmail login, credentials are stored at:

~/.config/mcmail/credentials.json

The file is created with 0600 permissions. It stores:

• username
• auth_token (valid 24h)
• valid_to (UNIX timestamp)
• password (for auto-refresh)

Usage

Authentication

# Log in interactively
mcmail login

# Show current login status
mcmail whoami

# Log out (clear cached token)
mcmail logout

Account Management

# List all accounts
mcmail accounts list

# List with search
mcmail accounts list --search alice

# Create a MailUser account
mcmail accounts create alice@example.com --password "SecurePass123!"

# Create with custom quota
mcmail accounts create alice@example.com --password "SecurePass123!" --quota 4096

# Show account details
mcmail accounts info alice@example.com

# Delete an account (prompts for confirmation)
mcmail accounts delete alice@example.com

# Delete without confirmation prompt
mcmail accounts delete alice@example.com --yes

Alias Management

# List all aliases
mcmail aliases list

# Create an alias
mcmail aliases create info@example.com --to alice@example.com

# Create alias with multiple recipients
mcmail aliases create team@example.com --to "alice@example.com,bob@example.com"

# Delete an alias
mcmail aliases delete info@example.com

# Delete without confirmation
mcmail aliases delete info@example.com --yes

Domain Management

# List all domains
mcmail domains list

JSON output

Append --json to any command to get machine-readable JSON:

mcmail accounts list --json
mcmail accounts info alice@example.com --json
mcmail whoami --json

Password Requirements

Account passwords must:

• Be at least 12 characters long
• Contain at least 1 uppercase and 1 lowercase letter
• Contain at least 1 digit

Examples

# Stateless one-liner (useful in scripts)
MCMAIL_USER=admin MCMAIL_PASSWORD=secret mcmail accounts list --json

# Login and use credentials file
mcmail login
mcmail accounts create deploy@myapp.com --password "Deploy-2026-Secure!"
mcmail aliases create noreply@myapp.com --to deploy@myapp.com
mcmail accounts info deploy@myapp.com

Requirements

• Node.js ≥ 18

License

MIT