You are currently browsing documentation for the master branch. Documentation for the stable 2024.06 branch can be found here.

Mailu command line

Managing domains, users and aliases can be done from CLI using the commands:

  • alias

  • alias-delete

  • domain

  • password

  • user

  • user-import

  • user-delete

  • config-update

  • config-export

  • config-import

alias

docker compose exec admin flask mailu alias foo example.net "mail1@example.com,mail2@example.com"

alias-delete

docker compose exec admin flask mailu alias-delete foo@example.net

domain

docker compose exec admin flask mailu domain example.net

password

docker compose exec admin flask mailu password myuser example.net 'password123'

user

docker compose exec admin flask mailu user myuser example.net 'password123'

user-import

primary difference with simple user command is that password is being imported as a hash - very useful when migrating users from other systems where only hash is known.

docker compose run --rm admin flask mailu user-import myuser example.net '$6$51ebe0cb9f1dab48effa2a0ad8660cb489b445936b9ffd812a0b8f46bca66dd549fea530ce' 'SHA512-CRYPT'

user-delete

Although the action is called “user-delete” the user is only deactivated by default. This is due to the fact mailu does not remove user-data (emails and webmail contacts) when a user is deleted. Add the flag -r to really delete the user after you have deleted user-data manually.

docker compose exec admin flask mailu user-delete foo@example.net

config-update

The sole purpose of this command is for importing users/aliases in bulk and synchronizing DB entries with external YAML template:

cat mail-config.yml | docker compose exec -T admin flask mailu config-update --delete-objects

where mail-config.yml looks like:

users:
  - localpart: foo
    domain: example.com
    password_hash: klkjhumnzxcjkajahsdqweqqwr

aliases:
  - localpart: alias1
    domain: example.com
    destination: "user1@example.com,user2@example.com"

without --delete-object option config-update will only add/update new values but will not remove any entries missing in provided YAML input.

Users

following are additional parameters that could be defined for users:

  • comment

  • quota_bytes

  • global_admin

  • enable_imap

  • enable_pop

  • forward_enabled

  • forward_destination

  • reply_enabled

  • reply_subject

  • reply_body

  • displayed_name

  • spam_enabled

  • spam_mark_as_read

  • spam_threshold

Alias

additional fields:

  • wildcard

config-export

The purpose of this command is to export the complete configuration in YAML or JSON format.

 $ docker compose exec -T admin flask mailu config-export --help

Usage: flask mailu config-export [OPTIONS] [FILTER]...

  Export configuration as YAML or JSON to stdout or file

Options:
  -f, --full                  Include attributes with default value.
  -s, --secrets               Include secret attributes (dkim-key, passwords).
  -d, --dns                   Include dns records.
  -c, --color                 Force colorized output.
  -o, --output-file FILENAME  Save configuration to file.
  -j, --json                  Export configuration in json format.
  -?, -h, --help              Show this message and exit.

Only non-default attributes are exported. If you want to export all attributes use --full. If you want to export plain-text secrets (dkim-keys, passwords) you have to add the --secrets option. To include dns records (mx, spf, dkim and dmarc) add the --dns option.

By default all configuration objects are exported (domain, user, alias, relay). You can specify filters to export only some objects or attributes (try: user or domain.name). Attributes explicitly specified in filters are automatically exported: there is no need to add --secrets or --full.

$ docker compose exec admin flask mailu config-export --output-file mail-config.yml

$ docker compose exec -T admin flask mailu config-export domain.dns_mx domain.dns_spf

$ docker compose exec -T admin flask mailu config-export user.email user.spam_threshold

config-import

This command imports configuration data from an external YAML or JSON source.

 $ docker compose exec -T admin flask mailu config-import --help

Usage: flask mailu config-import [OPTIONS] [FILENAME|-]

  Import configuration as YAML or JSON from stdin or file

Options:
  -v, --verbose   Increase verbosity.
  -s, --secrets   Show secret attributes in messages.
  -q, --quiet     Quiet mode - only show errors.
  -c, --color     Force colorized output.
  -u, --update    Update mode - merge input with existing config.
  -n, --dry-run   Perform a trial run with no changes made.
  -?, -h, --help  Show this message and exit.

To pass stdin correctly you have to use the -T option:

docker compose exec -T admin flask mailu config-import -nv < mail-config.yml

mail-config.yml contains the configuration and looks like this:

domain:
  - name: example.com
    alternatives:
      - alternative.example.com

user:
  - email: foo@example.com
    password_hash: '$2b$12$...'
    hash_scheme: MD5-CRYPT

alias:
  - email: alias1@example.com
    destination:
      - user1@example.com
      - user2@example.com

relay:
  - name: relay.example.com
    comment: test
    smtp: mx.example.com

config-import shows the number of created/modified/deleted objects after import. To suppress all messages except error messages use --quiet. By adding the --verbose switch the import gets more detailed and shows exactly what attributes changed. In all log messages plain-text secrets (dkim-keys, passwords) are hidden by default. Use --secrets to log secrets. If you want to test what would be done when importing without committing any changes, use --dry-run.

By default config-import replaces the whole configuration. --update allows to modify the existing configuration instead. New elements will be added and existing elements will be modified. It is possible to delete a single element or prune all elements from lists and associative arrays using a special notation:

Delete what?

notation

example

specific array object

- -key: id

- -name: example.com

specific list item

- -id

- -user1@example.com

all remaining array objects

- -key: null

- -email: null

all remaining list items

- -prune-

- -prune-

The -key: null notation can also be used to reset an attribute to its default. To reset spam_threshold to it’s default 80 use -spam_threshold: null.

A new dkim key can be generated when adding or modifying a domain, by using the special value dkim_key: -generate-.

This is a complete YAML template with all additional parameters that can be defined:

domain:
  - name: example.com
    alternatives:
      - alternative.tld
    comment: ''
    dkim_key: ''
    max_aliases: -1
    max_quota_bytes: 0
    max_users: -1
    signup_enabled: false

user:
  - email: postmaster@example.com
    comment: ''
    displayed_name: 'Postmaster'
    enable_imap: true
    enable_pop: false
    enabled: true
    fetches:
      - id: 1
        comment: 'test fetch'
        error: null
        host: other.example.com
        keep: true
        last_check: '2020-12-29T17:09:48.200179'
        password: 'secret'
        hash_password: true
        port: 993
        protocol: imap
        tls: true
        username: fetch-user
    forward_destination:
      - address@remote.example.com
    forward_enabled: true
    forward_keep: true
    global_admin: true
    manager_of:
      - example.com
    password: '$2b$12$...'
    hash_password: true
    quota_bytes: 1000000000
    reply_body: ''
    reply_enabled: false
    reply_enddate: '2999-12-31'
    reply_startdate: '1900-01-01'
    reply_subject: ''
    spam_enabled: true
    spam_mark_as_read: true
    spam_threshold: 80
    tokens:
      - id: 1
        comment: email-client
        ip: 192.168.1.1
        password: '$5$rounds=1$...'

alias:
  - email: email@example.com
    comment: ''
    destination:
      - address@example.com
    wildcard: false

relay:
  - name: relay.example.com
    comment: ''
    smtp: mx.example.com