mailcowctl

CLI for mailcow operators

mailcowctl

Script mailcow without clicking through the admin UI. mailcowctl talks to the mailcow REST API and covers domains, mailboxes, aliases, migration helpers, routing maps, resources, and quarantine operations.

Install Configure API access GitHub
Terminal demo showing mailcowctl commands that create and inspect mailcow resources
Terminal-first mailcow administration, with table, JSON, or YAML output.

Fast path

One API key, repeatable mail operations.

export MAILCOW_HOST=https://mail.example.org
export MAILCOW_API_KEY=000000-000000-000000-000000-000000

mailcowctl domain list
mailcowctl mailbox list --domain example.org -o json
printf '%s\n' "$NEW_PASSWORD" | mailcowctl mailbox create [email protected] \
  --name "Me" --quota 3072 --password-stdin

What it does

A practical surface for mailcow state.

The command set maps to the mailcow objects operators touch during provisioning, migration, routing changes, and day-to-day response.

Provisioning

Domains, mailboxes, aliases.

Create and edit hosted domains, mailbox quotas, passwords, aliases, and catch-all style routing from scripts.

domain mailbox alias
Migration

Move the mailcow-adjacent pieces.

Inspect DKIM records, create imapsync jobs, export sieve filters, recreate app passwords, and carry policy lists forward.

dkim syncjob apppass filter policy
Routing

Automate mail flow maps.

Manage transports, BCC maps, recipient rewrites, TLS policies, sender relay hosts, and forwarding hosts.

transport bcc recipient tlspolicy relayhost fwdhost
Operations

Handle live mailbox state.

Review quarantine, release messages, train ham, purge held mail, and manage calendar resources.

quarantine resource

Install

Use a release binary or build with Go.

Releases publish Linux and macOS archives for amd64 and arm64 with checksums. Go 1.22 or newer can install the latest version directly.

Release binary

# Download from:
https://github.com/elcamino/mailcowctl/releases

tar -xzf mailcowctl_<version>_<os>_<arch>.tar.gz
install -m 0755 mailcowctl /usr/local/bin/mailcowctl

Go install

go install github.com/elcamino/mailcowctl@latest

Source build

git clone https://github.com/elcamino/mailcowctl.git
cd mailcowctl
go test ./...
go build -o mailcowctl .

API access

Enable the mailcow API before using the CLI.

mailcow authenticates API calls with X-API-Key and restricts keys by source IP. Use a read-write key for commands that create, edit, delete, release, or learn mail.

In mailcow

  1. Open the mailcow admin UI as an administrator.
  2. Find the API access settings in system configuration.
  3. Create or set an API key and enable API access.
  4. Add each workstation, server, or CI runner IP to the API allow-list.
  5. Use a read-write key when mailcowctl should change mailcow state.

In mailcow-dockerized

Edit mailcow.conf on the mailcow host, or .env if that is how the deployment is managed.

API_KEY=$(openssl rand -hex 32)
API_ALLOW_FROM=127.0.0.1,203.0.113.10,198.51.100.20

Restart or recreate the affected mailcow containers after changing the API settings.

Configure mailcowctl

Choose flags, environment variables, or a profile file.

Resolution order is flags first, then environment, then $XDG_CONFIG_HOME/mailcowctl/config.yaml or ~/.config/mailcowctl/config.yaml.

Environment

export MAILCOW_HOST=https://mail.example.org
export MAILCOW_API_KEY="$API_KEY"
mailcowctl domain list

Flags

mailcowctl \
  --host https://mail.example.org \
  --api-key "$MAILCOW_API_KEY" \
  domain list

Profile file

current_profile: prod
profiles:
  prod:
    host: https://mail.example.org
    api_key: 000000-000000-000000-000000-000000

Examples

Commands that fit shell scripts and runbooks.

mailcowctl domain create example.org \
  --description Example \
  --mailboxes 10 \
  --aliases 400 \
  --quota 10240
mailcowctl alias create [email protected] \
  --goto [email protected]

mailcowctl alias delete [email protected] --yes
mailcowctl dkim get example.org --dns
mailcowctl filter get 42 -o json
mailcowctl syncjob list
mailcowctl quarantine list --rcpt [email protected]
mailcowctl quarantine release 12345
mailcowctl quarantine delete 12345 --yes