Back to the main page


Deliver outbound mail via SMTP

This component delivers outbound mail to remote servers (and, in some cases, the local server) as well as generating bounce notification message upon failure of delivery.

Building & Prerequisites

The following packages are required for building this module (Debian packages are listed) A build of only this specific module can be initiated by running make in cmail-dispatchd/

Setup information

This module needs read and write access to the master database AS WELL AS the folder containing it. Recommended practice is creating a dedicated user and specifying that in the configuration in order to have the module drop its privileges after binding the ports.

Run the module without specifying a logfile in the configuration at first, in order to test its operation and track down any misconfigurations. Specifying a logfile allows the module to daemonize itself and detach from the starting shell.

Configuration file

The configuration file contains multiple lines, each specifying one of the following configuration directives. Lines are read from this file consecutively. Most directives become active the moment they are read. An example configuration file with sane defaults (save for the announce, bounce_from and bind options) can be found in the example-configs/ folder in the main repo.
Directive Parameters
Comments Verbatim
verbosity Integer between 0 and 4 Set log output verbosity. Higher values include messages for lower values.
  • 0 - Errors & Warnings only (Default)
  • 1 - Informational messages
  • 2 - Currently not specified
  • 3 - Debug messages
  • 4 - All input and output
logfile Path to log file If not specified, cmail-dispatchd will log to stderr and will not be able to detach from the calling shell
pidfile Path to pid file Write the PID of the daemonized process to the specified file. If not specified, no file is created. PID files are used by daemon supervisors such as systemd for stopping services.
user Username to switch to The module will change its executing user to the one specified. Only works when started as root. This is one of the few options not immediately taking effect.
group Group name to switch to The module will change its executing group to the on specified. Only works when started as root. This is one of the few options not immediately taking effect.
database Path to master database The executing user needs read AND write access to the master database file as well as the folder containing it
announce Hostname to announce This parameter will be announced to remote SMTP servers in the HELO/EHLO command. It is good practice to have this resolve back to the connecting host
bounce_from Bounce originator address The sending address to appear in bounce notifications
interval Database check interval in seconds This option configures the interval in which cmail-dispatchd checks the database for outbound mail
retries Maximum number of delivery attempts Configure how many times cmail-dispatchd will retry mail delivery upon encountering a temporary failure
retryinterval Mail retry interval in seconds The minimum time between two delivery attempts for a single mail item
tls_padding (optional)
Maximum number of TLS padding operations
In order to provide some obfuscation to counter a passive attacker, cmail-dispatchd can run a random number of useless operations (NOOP/RSET) over the TLS layer before actually starting the mail transaction.
tls_trustfile (required when compiled without -DCMAIL_NO_TLS)
CA certificate file
Trust roots to be used for certificate validation. Currently not practically used as email certificates are usually self-signed.
bounce_copy (optional)
Space separated list of additional recipients for bounce notifications
Bounce notifications may be sent to additional recipients (such as the system administrator) in order to detect problems
bind (optional)
Bind address for outbound connections
Hosts with multiple IP addresses may prefer to use those that have a corresponding PTR record (reverse DNS entry) associated with them for outbound mail transfers. This should usually be set to the same value as the announce option.
portprio Space separated list of port specifications The ports to be tried on remote servers, prioritized from left to right. Port specifications are supplied in the form <Port number>[@(tls|starttls)], e.g.
  • 465@tls
  • 25@starttls
  • 25

Database configuration


Resources & Further reading