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 [email protected] --password "SecurePass123!"

# Create with custom quota
mcmail accounts create [email protected] --password "SecurePass123!" --quota 4096

# Show account details
mcmail accounts info [email protected]

# Delete an account (prompts for confirmation)
mcmail accounts delete [email protected]

# Delete without confirmation prompt
mcmail accounts delete [email protected] --yes

Alias Management

# List all aliases
mcmail aliases list

# Create an alias
mcmail aliases create [email protected] --to [email protected]

# Create alias with multiple recipients
mcmail aliases create [email protected] --to "[email protected],[email protected]"

# Delete an alias
mcmail aliases delete [email protected]

# Delete without confirmation
mcmail aliases delete [email protected] --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 [email protected] --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 [email protected] --password "Deploy-2026-Secure!"
mcmail aliases create [email protected] --to [email protected]
mcmail accounts info [email protected]

Requirements

• Node.js ≥ 18

License

MIT