CLI Commands

Global Flags

These flags work with every command:

mailgator serve

Start the IMAP and SMTP proxy. This is the main command you will use to run Mailgator.

mailgator serve
mailgator serve -c /etc/mailgator/config.toml

When you run serve, Mailgator:

1. Loads and validates your config file
2. Loads the secrets file (creates it if missing)
3. Auto-generates an encryption key if you have ask rules configured
4. Verifies your license is valid
5. Checks that upstream IMAP and SMTP servers are reachable
6. Opens the IMAP and SMTP listener ports
7. Starts the web server if ask rules are configured
8. Begins proxying traffic and enforcing rules

The proxy runs until you stop it with Ctrl+C (SIGINT) or send SIGTERM.

# Example output
smtp listening on 127.0.0.1:1587 -> smtp.gmail.com:587
imap listening on 127.0.0.1:1993 -> imap.gmail.com:993
web listening on 127.0.0.1:8080

mailgator config init

Create a new template configuration file. This gives you a starting point with all available options commented out and documented.

mailgator config init
mailgator config init -c my-config.toml

The command will refuse to overwrite an existing file. If a config already exists at the target path, you will see an error message.

mailgator config validate

Validate your configuration file and test connectivity. This is useful for catching errors before starting the proxy.

mailgator config validate

The validation checks:

• Config file syntax (valid TOML)
• Required fields are present
• Addresses are valid host:port format
• TLS modes are valid
• Rule names are present and operations are recognized
• Upstream IMAP and SMTP servers are reachable
• Listen ports are available (not in use by another process)

# Example output
[✓] smtp upstream smtp.gmail.com:587 reachable
[✓] imap upstream imap.gmail.com:993 reachable
[✓] smtp listen 127.0.0.1:1587 available
[✓] imap listen 127.0.0.1:1993 available
[✓] config valid

mailgator license login

Activate your license by logging in through your browser. This is the recommended way to set up your license.

mailgator license login

How it works:

1. Mailgator starts a temporary local web server
2. Opens your browser to the mailgator.io login page
3. You sign in with your account
4. The license token is sent back to the local server
5. The token is saved to your secrets file

If the browser cannot be opened (e.g., on a headless server), the command prints the URL so you can open it manually. The login times out after 5 minutes.

mailgator license show

Display information about your current license.

mailgator license show

# Example output
Status: valid
Type: pro
Expires: 2025-12-31

mailgator license purchase

Display the URL where you can purchase or upgrade your license.

mailgator license purchase

# Example output
Visit this link to purchase a premium license:

https://mailgator.io/purchase

After purchase, run: mailgator license refresh

mailgator license refresh

Force an immediate license refresh from the server. Useful after purchasing a license or if you want to verify your license status.

mailgator license refresh

During normal operation, Mailgator automatically refreshes your license every hour in the background. This command forces an immediate check.

Example Workflows

First-time setup

# 1. Create config
mailgator config init

# 2. Edit config with your server details
vim mailgator-config.toml

# 3. Validate before running
mailgator config validate

# 4. Log in to activate license
mailgator license login

# 5. Start the proxy
mailgator serve

Using a custom config path

# All commands accept -c to specify config location
mailgator config init -c /etc/mailgator/config.toml
mailgator config validate -c /etc/mailgator/config.toml
mailgator license login -c /etc/mailgator/config.toml
mailgator serve -c /etc/mailgator/config.toml

After purchasing a license

# Refresh to pick up the new license
mailgator license refresh

# Verify it worked
mailgator license show