Setup Qmail

Configuring qmail to relay through MailChannels routes all outbound mail through Outbound Filtering before delivery, protecting your sending reputation. Due to qmail’s modular structure, setup requires patching, script creation, and smarthost configuration.

Modifying qmail configuration files, applying patches, and creating scripts incorrectly can disrupt email services. Back up your configuration files and qmail source before making changes. Test in a non-production environment if possible.

Audience: Server administrators managing qmail servers. Familiarity with qmail configuration, control files, and patching processes is essential.

Prerequisites

Root access to your qmail server
Your MailChannels SMTP username and password
qmail patched to enable SMTP authentication (AUTH SMTP) — consult qmail documentation to apply the SMTPAUTH patch if not already done
qmail patched with the qmailqueue patch (e.g., Bruce Guenter’s patch) to allow modifying headers before messages are queued

Configuration Steps

Configure the X-AuthUser Header

The X-AuthUser header identifies the responsible sender in your system. MailChannels uses it to isolate compromised accounts without blocking other senders. This step uses Bruce Guenter’s qmailqueue patch and qmail-qfilter.Install qmail-qfilter:Apply Bruce Guenter’s qmail-qfilter patch if not already applied. Download the patch (search for “qmailqueue-patch”) and apply it to your qmail source, then recompile qmail.Modify your qmail-smtpd run script:Locate your run script (e.g., /service/qmail-smtpd/run or /var/qmail/supervise/qmail-smtpd/run). Add or modify the QMAILQUEUE environment variable before the exec qmail-smtpd line:

export QMAILQUEUE="/var/qmail/bin/qmail-authuser-filter.sh"

Create the filter shell script:Create /var/qmail/bin/qmail-authuser-filter.sh with the following content, then make it executable:

/var/qmail/bin/qmail-authuser-filter.sh

#!/bin/sh
# Passes the email through qmail-qfilter with the header injection script.
exec /usr/local/bin/qmail-qfilter /var/qmail/bin/qmail-authuser-header.pl

chmod +x /var/qmail/bin/qmail-authuser-filter.sh

Adjust the path to qmail-qfilter if it is installed elsewhere.

Create the Perl header script:Create /var/qmail/bin/qmail-authuser-header.pl with the following content, then make it executable:

/var/qmail/bin/qmail-authuser-header.pl

#!/usr/bin/perl
# Adds the X-AuthUser header using the TCPREMOTEINFO environment variable.
# TCPREMOTEINFO should be set by tcpserver to the authenticated user.

my $auth_user = $ENV{'TCPREMOTEINFO'};

if ($auth_user) {
    print "X-AuthUser: $auth_user\n";
} else {
    my $fallback_user = $ENV{'SMTPREMOTEIP'} || "unknown_sender";
    print "X-AuthUser: $fallback_user\n";
}

while(<STDIN>) {
    print;
}
exit 0;

chmod +x /var/qmail/bin/qmail-authuser-header.pl

For this script to capture the authenticated user, your tcpserver setup for qmail-smtpd must correctly set TCPREMOTEINFO upon successful SMTP authentication.

Configure MailChannels as the smart host

Edit or create /var/qmail/control/smtproutes. To route all external email through MailChannels, add the following line — replacing the placeholders with your actual MailChannels SMTP credentials:

/var/qmail/control/smtproutes

:smtp.mailchannels.net:25 YourMailChannelsUsername YourMailChannelsPassword

If outbound TCP port 25 is blocked in your network, use port 587 or 2525 instead::smtp.mailchannels.net:587 YourMailChannelsUsername YourMailChannelsPasswordThe leading colon : means this rule applies to all domains not matched by more specific entries in smtproutes and not listed in /var/qmail/control/locals.

Restart qmail services

Restart the relevant qmail services for all changes to take effect. The exact command varies depending on your installation:

qmailctl restart

Or, if managing services individually with daemontools:

svc -t /service/qmail-smtpd
svc -t /service/qmail-send

Consult your qmail installation documentation for the precise commands.

Verify the configuration

Send test emails

Send emails from an account on your server to a few external addresses (e.g., Gmail, Outlook.com) to confirm delivery.

Check mail logs

Examine your qmail logs (often under /var/log/qmail/, or managed by multilog to directories like /var/log/qmail/qmail-send/current and /var/log/qmail/qmail-smtpd/current).

Look for lines indicating successful delivery via smtp.mailchannels.net.
Check for any authentication or relay errors.

Review the MailChannels Host Console

Log in to your MailChannels Host Console and check Log Search to confirm your test messages are being processed. Verify that the X-AuthUser header is present and correctly identifies the sender — the third field of the senderID value will contain the value qmail inserted into X-AuthUser.

Optional: advanced qmail settings

These settings are configured by creating or editing files in /var/qmail/control/. Restart qmail-send (or run a full qmailctl restart) after making changes.

Queue lifetime (queuelifetime) — how long in seconds a message stays in the queue before bouncing. Default is 604,800 seconds (7 days).
echo "172800" > /var/qmail/control/queuelifetime
Server identity (me) — sets the FQDN of your mail server, used in HELO and other operations.
echo "mail.yourserver.example.com" > /var/qmail/control/me
HELO hostname (helohost) — overrides the HELO name used by qmail-remote. If not set, the value from me is used.
echo "smtp-out.yourserver.example.com" > /var/qmail/control/helohost
Remote delivery concurrency (concurrencyremote) — maximum simultaneous remote SMTP delivery processes. Default is 20.
echo "50" > /var/qmail/control/concurrencyremote
Local delivery concurrency (concurrencylocal) — maximum simultaneous local delivery processes. Default is 10.
echo "20" > /var/qmail/control/concurrencylocal
Connection timeout (timeoutconnect) — seconds qmail-remote waits for a connection. Default is 60 seconds.
echo "30" > /var/qmail/control/timeoutconnect
Remote response timeout (timeoutremote) — seconds qmail-remote waits for each response after connecting. Default is 1,200 seconds (20 minutes).
echo "600" > /var/qmail/control/timeoutremote

Get Started

Monitoring & Alerts

Troubleshooting

Billing & Account Management

Prerequisites

Configuration Steps

Verify the configuration

Optional: advanced qmail settings

​Prerequisites

​Configuration Steps

​Verify the configuration

​Optional: advanced qmail settings

Prerequisites

Configuration Steps

Verify the configuration

Optional: advanced qmail settings