> ## 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 Postfix

> Configure Postfix as a MailChannels outbound relay using SASL authentication, TLS encryption, and smart host routing to smtp.mailchannels.net.

Postfix is one of the most widely deployed MTAs on Linux servers. By configuring it to relay through MailChannels, all outbound mail is filtered for spam before delivery, protecting your sending reputation. This guide walks you through setting up the relay host, configuring SASL authentication, adding a sender identification header, and verifying the configuration.

<Warning>
  Modifying Postfix configuration files can disrupt email delivery if done incorrectly. Back up `/etc/postfix/main.cf` and any related files before making changes.
</Warning>

## Prerequisites

* Root or `sudo` access to your Postfix server
* Your MailChannels SMTP username and password
* Postfix installed and running
* The `libsasl2-modules` package (or the equivalent for your OS) installed to support SASL authentication

## Configure the relay

<Steps>
  <Step title="Edit main.cf">
    Open `/etc/postfix/main.cf` in a text editor and add or update the following lines. These settings tell Postfix to relay all outbound mail through MailChannels and to authenticate with your credentials over TLS.

    ```ini /etc/postfix/main.cf theme={null}
    # Relay all non-local mail through MailChannels
    relayhost = smtp.mailchannels.net:25

    # Enable SASL authentication for the SMTP client
    smtp_sasl_auth_enable = yes
    smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd
    smtp_sasl_security_options = noanonymous

    # Enable TLS encryption (required by MailChannels)
    smtp_use_tls = yes
    ```

    <Note>
      If outbound TCP port 25 is blocked on your network, substitute port `587` or `2525` in the `relayhost` value (for example, `smtp.mailchannels.net:587`).
    </Note>
  </Step>

  <Step title="Create the SASL password file">
    Create `/etc/postfix/sasl_passwd` and add the following line, replacing the placeholder values with your actual MailChannels credentials.

    ```text /etc/postfix/sasl_passwd theme={null}
    smtp.mailchannels.net:25    YOUR_USERNAME:YOUR_PASSWORD
    ```

    If you used an alternate port in `relayhost`, use the same host-and-port combination here — for example, `smtp.mailchannels.net:587 YOUR_USERNAME:YOUR_PASSWORD`.
  </Step>

  <Step title="Generate the lookup table">
    Run `postmap` to compile the password file into a Berkeley database that Postfix can query at runtime.

    ```bash theme={null}
    sudo postmap /etc/postfix/sasl_passwd
    ```
  </Step>

  <Step title="Restrict file permissions">
    Limit read access to the password file and its compiled database to the root user only.

    ```bash theme={null}
    sudo chown root:root /etc/postfix/sasl_passwd /etc/postfix/sasl_passwd.db
    sudo chmod 600 /etc/postfix/sasl_passwd /etc/postfix/sasl_passwd.db
    ```
  </Step>

  <Step title="Add the X-AuthUser header (recommended)">
    MailChannels uses the `X-AuthUser` header to track which authenticated user or script sent a message. This is important for abuse mitigation and sender reputation management.

    First, enable header checks in `main.cf`:

    ```ini /etc/postfix/main.cf theme={null}
    header_checks = regexp:/etc/postfix/header_checks
    ```

    Then create `/etc/postfix/header_checks` with the following content. The regular expression prepends the `X-AuthUser` header using the SASL-authenticated username whenever a `From:` line is detected.

    ```text /etc/postfix/header_checks theme={null}
    /^From:/ PREPEND X-AuthUser: ${sasl_username}
    ```

    <Note>
      This works when `${sasl_username}` is populated — typically for mail submitted over port 587 with SASL authentication. For local scripts that inject mail without authenticating, you may need a milter or a custom submission wrapper to populate the header reliably.
    </Note>
  </Step>

  <Step title="Check and reload Postfix">
    Validate the configuration for syntax errors, then reload Postfix to apply all changes.

    ```bash theme={null}
    sudo postfix check
    sudo postfix reload
    ```

    If `reload` is not sufficient (for example, after major structural changes), perform a full restart instead.

    ```bash theme={null}
    sudo systemctl restart postfix
    ```
  </Step>
</Steps>

## Verify the configuration

After reloading Postfix, confirm that mail is flowing through MailChannels correctly.

1. **Send test emails.** Send messages from an address on your server to a few external destinations (Gmail, Outlook, and so on).
2. **Check your mail logs.** Look at `/var/log/mail.log` or `/var/log/maillog` (or use `journalctl -u postfix`) for lines like `relay=smtp.mailchannels.net` and `status=sent`. Authentication errors or TLS failures will also appear here.
3. **Review the MailChannels console.** Log in to your MailChannels Host Console and go to **Outbound > Activity > LogSearch** to confirm your test messages appear and are being processed. The third field of the `senderID` (or `sid=`) header reflects the value you placed in `X-AuthUser`.

## Optional: domain-specific routing

If you want to relay only certain sender domains through MailChannels — or exclude specific domains — you can use `sender_dependent_relayhost_maps` instead of a global `relayhost`.

<Steps>
  <Step title="Update main.cf">
    Comment out or remove the global `relayhost` line and add the following:

    ```ini /etc/postfix/main.cf theme={null}
    # sender_dependent_relayhost_maps replaces the global relayhost setting
    sender_dependent_relayhost_maps = hash:/etc/postfix/sender_relay
    ```
  </Step>

  <Step title="Create the sender relay map">
    Create `/etc/postfix/sender_relay`. Use square-bracket notation around the host to prevent MX lookups.

    <CodeGroup>
      ```text Relay specific domains only theme={null}
      # Only these domains relay through MailChannels
      example.com         [smtp.mailchannels.net]:25
      another-domain.net  [smtp.mailchannels.net]:25
      ```

      ```text Exclude a domain, relay everything else theme={null}
      # Exclude one domain; route all others through MailChannels
      exclude-this.com    DUNNO
      @                   [smtp.mailchannels.net]:25
      ```
    </CodeGroup>
  </Step>

  <Step title="Compile the map and reload">
    ```bash theme={null}
    sudo postmap /etc/postfix/sender_relay
    sudo postfix reload
    ```
  </Step>
</Steps>

## Optional: queue lifetime tuning

Adjust how long Postfix holds messages in the queue before bouncing them. Add or modify these parameters in `main.cf`, then run `sudo postfix reload`.

```ini /etc/postfix/main.cf theme={null}
# Maximum time a message stays in the queue before bouncing (default: 5d)
maximal_queue_lifetime = 2d

# Maximum time a bounce notification stays in the queue (default: 5d)
bounce_queue_lifetime = 1d
```