#command-line #domain #password #username

app vmail-rs

A CLI client for vmail (mailserver setup with Dovecot, Postfix, MySQL, Rspamd)

1 unstable release

0.4.0 Jan 13, 2021



Rust 1K SLoC // 0.0% comments BASH 652 SLoC SQL 45 SLoC // 0.0% comments Shell 10 SLoC


Build status License Crates.io

vmail-rs is a command line tool for managing a mail-server database based on the great HowTo (german version) from Thomas Leister written in Rust. Although the tutorial is using a MySQL/MariaDB database, this command line tool also supports postgres.


Make sure you have a working mail setup as described in the tutorial. You also need C libraries for your database client. For ubuntu, this is the libmysqlclient-dev package (or libpq-dev, if you are using postgres).

Further, as vmail-rs is written in Rust, you should have a working rustup/cargo setup.


vmail-rs contains the cli tool vmail-cli. By default, MySQL/MariaDB is used. To enable postgres support, add --features postgres to the following cargo commands.

From crates.io

Install vmail-rs via cargo.

> cargo install vmail-rs

From github

# default mysql [default]
> cargo install --git https://github.com/awidegreen/vmail-rs

# use postgres
> cargo install --features postgres --git https://github.com/awidegreen/vmail-rs

Build from sources

Clone the repo and run

> cargo install

or the release version

> cargo install --release


vmail-rs uses Rust's dotenv crate to create environment configuration from a .env file.

Create a .env in the current directory containing the DATABASE_URL configuration parameter (be aware of the URI character encoding for the password).


If you are using postgres, a key-value format may be used instead of an URL.

Use the command help to get started.

vmail-cli --help

NOTE: all subcommands can also be shortcut'd. vmail-cli will automatically defer the correct command: vmail-cli u s equals vmail-cli user show

The user subcommands can work on default domain. Therefore set DEFAULT_DOMAIN=mydomain.org in the .env file. More information below.

Subcommand domain

Available subcommands are:

  • add
  • help
  • remove
  • show

Use help for more information.

vmail-cli domain add mydomain.org

vmail-cli domain show

vmail-cli domain remove mydomain.org

Subcommand user

As the name suggests, this subcommand is used to mange the users/accounts within the database. In order to add a new user, the associated domain need to exist.

Available subcommands are:

  • add
  • edit
  • help
  • password
  • remove
  • show

Use help for more information.

The user commands will assume a default domain, which can be set in .env: DEFAULT_DOMAIN=mydomain.org. If you want to use different domain, the parameter --domain|-d for the user subcommand should be used. Further, if no default domain has been set, the domain parameter needs to be provided.

vmail-cli user add foo

vmail-cli user -d otherdomain.org add foo

vmail-cli user show

vmail-cli user remove foo

vmail-cli user -d otherdomain.org remove foo

Subcommand alias

In order to add a new alias, the associated user and domain need to exist.

Available subcommands are:

  • add
  • help
  • remove
  • show

Use help for more information.

vmail-cli alias add bar mydomain.org foo

vmail-cli alias add hello mydomain.org foo otherdomain.org

vmail-cli alias show

vmail-cli alias show foo mydomain.org

vmail-cli alias remove bar mydomain.org

In order to add/remove a catch-all alias for a domain, the '%' (percentage) should be used as a username for the alias. Make sure that your database supports such feature.

vmail-cli alias add % mydomain.org foo

vmail-cli alias remove % mydomain.org


Shell completions

For bash, move shell/vmail-cli.bash to $XDG_CONFIG_HOME/bash_completion/ or /etc/bash_completion.d/.

For fish, move shell/vmail-cli.fish to $HOME/.config/fish/completions/.

For zsh, move shell/_vmail-cli to one of your $fpath directories.

For regenerating the shell completions, run shell/gen_comp.sh from the root of the repository. The files in shell/ will be updated accordingly. This will use vmail-cli hidden completions subcommand.

How to contribute

Create new issues if you find bugs or want to a new features. Pull requests are very welcomed.


Copyright (C) 2021 by Armin Widegreen

This is free software, licensed under The BSD-3-Clause.


~96K SLoC