Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Build status License

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.


Install vmail-rs via cargo.

> cargo install vmail-rs

From github

# default mysql [default]
> cargo install --git

# use postgres
> cargo install --features postgres --git

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 in the .env file. More information below.

Subcommand domain

Available subcommands are:

  • add
  • help
  • remove
  • show

Use help for more information.

# Create domain
vmail-cli domain add

# Show domains
vmail-cli domain show

# Delete domain
vmail-cli domain remove

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: 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.

# Create user for default domain
vmail-cli user add foo

# Create user for other domain
vmail-cli user -d add foo

# Show users for default domain
vmail-cli user show

# Delete user for default domain
vmail-cli user remove foo

# Delete user other domain
vmail-cli user -d 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.

# Create alias '' for existing user-account ''
vmail-cli alias add bar foo

# Create alias '' for existing user-account ''
vmail-cli alias add hello foo

# Show aliases for all user accounts
vmail-cli alias show

# Show aliases for single user account
vmail-cli alias show foo

# Delete alias ''
vmail-cli alias remove bar

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.

# Add catch-all alias for '' domain (alias for user 'foo')
vmail-cli alias add % foo

# Remove catch-all alias for '' domain
vmail-cli alias remove %


Shell completions

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

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

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

For regenerating the shell completions, run shell/ 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.


Command line mailbox account management tool for vmail (MySQL)







No packages published

Contributors 4