小橘
c12c1913bc
- Authentication: login / logout / whoami with token caching - Accounts: list / create / delete / info - Aliases: list / create / delete - Domains: list - TypeScript + ESM + commander.js - Node fetch (no axios) - Table and --json output modes - Auto token refresh on expiry - MCMAIL_HOST / MCMAIL_USER / MCMAIL_PASSWORD env var support
162 lines
3.3 KiB
Markdown
162 lines
3.3 KiB
Markdown
# 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)
|
|
|
|
```bash
|
|
npm install -g mcmail
|
|
```
|
|
|
|
### From source
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# Log in interactively
|
|
mcmail login
|
|
|
|
# Show current login status
|
|
mcmail whoami
|
|
|
|
# Log out (clear cached token)
|
|
mcmail logout
|
|
```
|
|
|
|
### Account Management
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# List all domains
|
|
mcmail domains list
|
|
```
|
|
|
|
### JSON output
|
|
|
|
Append `--json` to any command to get machine-readable JSON:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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
|