Back to the main page


Configure inbound path expressions for cmail

cmail-admin-address allows the administrator of a cmail server system to create, modify and delete address entries, which are tuples of an address expression, an address order and routing information describing how mail adressed to the path is to be handled. Inbound paths are matched against the set of all configured entries, ordered totally by the address order, with the highest order value being matched first. Expressions may contain arbitrary-length wildcards (%) and single-character wildcards (_). Further information about the exact matching semantics may be found by referring to the SQLite documentation.

Building & Prerequisites

The following packages are required for building this utility (Debian packages are listed) A build of only this specific binary can be initiated by running make from within cmail-admin/address in the main repository. A build of all administration utilities may be initiated by running make from within cmail-admin/.

Setup information

The utility is automatically installed to a location accessible by the administrator with the make install step of the installation (/usr/sbin/ by default).


This utility needs read and write access to the master database AS WELL AS the folder containing it. The location of the master database file is assumed to be /etc/cmail/databases/master.db3 by default and can be overridden by specifying either the --dbpath command line option or the CMAIL_MASTER_DB environment variable when running this utility.

Specifying the --help argument to an invocation prints additional information about the utility.

The cmail-admin utilities operate in one of several modes, as specified in the table below. Modes may optionally accept mode-specific arguments. Changes in cmail configuration databases become active immediately, requiring no restart of the system.

Modes of operation

Mode Arguments
variable [optional] verbatim
Description Example
list [expression] List all address entries currently known to the system. Optionally, filter the list for entries matching expression. cmail-admin-address list mpease%
test mailpath Test a mailpath against the inbound address database, showing entries that would match. cmail-admin-address test
add expression router [router-argument [order]] Add an inbound path entry for the provided expression, to be handled by the specified router. Some routers may require a router-argument. Optionally, an order value may be provided, which will be assigned to the path unless there is already an active entry using that order. See below for a table of valid router values. cmail-admin-address add "" store cbdev
swap first second Swap the order values of the two entries indicated by the given order values first and second. cmail-admin-address swap 9001 9002
delete order Delete the expression entry assigned the given order. cmail-admin-address delete 9001

Inbound path routers

Inbound routers are processing functions applied to incoming mail for each path in the recipients list, some of wich take an additional argument.
Router Arguments Description
store user Store the received mail to the inbox of user. Note that this does not resolve aliases. If user is not set or not a valid user, this router behaves the same way as the reject router.
handoff remote-spec Have incoming mail for this path be handled by a remote mail server (smart host) by simply reusing the original envelope with the new remote. If remote-spec is not set, this router behaves the same way as the reject router. If the remote-spec is invalid, the outbound SMTP client will generate a bounce notification message after a configured amount of retries.

A remote-spec must consist of a host name, optionally prefixed by authentication information in the form user:password@hostname and optionally trailed by a non-default port and TLS mode specification of the form hostname:port/tlsmode. tlsmode must be one of none (default), starttls or tlsonly. When a remote port is specified, only that port is connected to and any additional ports configured in the cmail-dispatchd configuration are ignored for that remote.

The optional parts of a remote-spec may be combined, for example to form
redirect new-recipient Rewrite the envelope recipient of the mail according to new-recipient, which may optionally contain any of the following variables:
  • (to-local) - will be replaced with the local part of the recipient path
  • (from-local) - will be replaced with the local part of the reverse path
  • (to-domain) - will be replaced with the domain part of the recipient path
  • (from-domain) - will be replaced with the domain part of the reverse path
If new-recipient is not set, this router will behave the same way as the reject router. If new-recipient is an invalid path, the outbound SMTP client will generate a bounce notification message after a configured amount of retries. Note that no router rewrites the header or body section of a mail. Therefore, the original recipient may still appear in the relevant headers.
reject [reason] Reject the recipient path (SMTP 551), optionally presenting reason as failure reason.
drop Accept but quietly drop incoming mail for this recipient path.