> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mailchannels.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup Qmail

> Configure qmail to relay outbound mail through MailChannels Outbound Filtering using SMTP authentication, X-AuthUser sender identification headers, and smtproutes smarthost configuration.

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.

<Warning>
  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.
</Warning>

**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

<Steps>
  <Step title="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:

    ```bash theme={null}
    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:

    ```sh /var/qmail/bin/qmail-authuser-filter.sh theme={null}
    #!/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
    ```

    ```bash theme={null}
    chmod +x /var/qmail/bin/qmail-authuser-filter.sh
    ```

    <Note>
      Adjust the path to `qmail-qfilter` if it is installed elsewhere.
    </Note>

    **Create the Perl header script:**

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

    ```perl /var/qmail/bin/qmail-authuser-header.pl theme={null}
    #!/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;
    ```

    ```bash theme={null}
    chmod +x /var/qmail/bin/qmail-authuser-header.pl
    ```

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

  <Step title="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:

    ```text /var/qmail/control/smtproutes theme={null}
    :smtp.mailchannels.net:25 YourMailChannelsUsername YourMailChannelsPassword
    ```

    <Note>
      If outbound TCP port 25 is blocked in your network, use port `587` or `2525` instead:

      `:smtp.mailchannels.net:587 YourMailChannelsUsername YourMailChannelsPassword`

      The 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`.
    </Note>
  </Step>

  <Step title="Restart qmail services">
    Restart the relevant qmail services for all changes to take effect. The exact command varies depending on your installation:

    ```bash theme={null}
    qmailctl restart
    ```

    Or, if managing services individually with daemontools:

    ```bash theme={null}
    svc -t /service/qmail-smtpd
    svc -t /service/qmail-send
    ```

    Consult your qmail installation documentation for the precise commands.
  </Step>
</Steps>

## Verify the configuration

<Steps>
  <Step title="Send test emails">
    Send emails from an account on your server to a few external addresses (e.g., Gmail, Outlook.com) to confirm delivery.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Review the MailChannels Host Console">
    Log in to your [MailChannels Host Console](https://console.mailchannels.net) 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`.
  </Step>
</Steps>

## 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).

  ```bash theme={null}
  echo "172800" > /var/qmail/control/queuelifetime
  ```

* **Server identity (`me`)** — sets the FQDN of your mail server, used in HELO and other operations.

  ```bash theme={null}
  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.

  ```bash theme={null}
  echo "smtp-out.yourserver.example.com" > /var/qmail/control/helohost
  ```

* **Remote delivery concurrency (`concurrencyremote`)** — maximum simultaneous remote SMTP delivery processes. Default is 20.

  ```bash theme={null}
  echo "50" > /var/qmail/control/concurrencyremote
  ```

* **Local delivery concurrency (`concurrencylocal`)** — maximum simultaneous local delivery processes. Default is 10.

  ```bash theme={null}
  echo "20" > /var/qmail/control/concurrencylocal
  ```

* **Connection timeout (`timeoutconnect`)** — seconds qmail-remote waits for a connection. Default is 60 seconds.

  ```bash theme={null}
  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).

  ```bash theme={null}
  echo "600" > /var/qmail/control/timeoutremote
  ```