npm package: @oc-forge/mcmail
Description: Mailcheap CLI — manage your mail server from the terminal
Author: 小橘
Latest version: 0.1.0

# 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