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

> Configure Zimbra to relay outbound mail through MailChannels using SMTP authentication, smart host routing, and the X-AuthUser sender header.

This guide walks you through configuring Zimbra to relay all outbound mail through MailChannels Outbound Filtering and adding the `X-AuthUser` header for per-sender reputation tracking.

## Prerequisites

* Root or administrative access to your Zimbra server
* Your MailChannels SMTP username and password

## Configure the relay

<Steps>
  <Step title="Open Global Settings in the Zimbra Admin Console">
    Navigate to `https://<your-zimbra-server>:7071` and log in with your admin credentials.

    Go to **Configure** > **Global Settings** and select the **MTA** tab.
  </Step>

  <Step title="Set the relay smart host">
    Configure the following values:

    | Field                               | Value                           |
    | ----------------------------------- | ------------------------------- |
    | **Relay MTA for external delivery** | `smtp.mailchannels.net`         |
    | **SMTP Port**                       | `587`                           |
    | **TLS encryption**                  | Enabled                         |
    | **Relay Authentication Username**   | Your MailChannels SMTP username |
    | **Relay Authentication Password**   | Your MailChannels SMTP password |

    Click **Save**.
  </Step>
</Steps>

## Add the X-AuthUser header

MailChannels uses the `X-AuthUser` header to identify the authenticated sender and track per-sender reputation. Messages without this header are treated as forwarded mail and subject to different policies.

Zimbra uses Postfix as its MTA, so the header is added via a Postfix sender access map.

<Steps>
  <Step title="Add the smtpd_sender_restrictions directive">
    Open `/opt/zimbra/conf/main.cf`:

    ```bash theme={null}
    sudo nano /opt/zimbra/conf/main.cf
    ```

    Add the following line to include the custom header access map:

    ```text /opt/zimbra/conf/main.cf theme={null}
    smtpd_sender_restrictions = check_sender_access hash:/opt/zimbra/conf/custom_header
    ```
  </Step>

  <Step title="Create the custom header file">
    Create `/opt/zimbra/conf/custom_header`:

    ```bash theme={null}
    sudo nano /opt/zimbra/conf/custom_header
    ```

    Add the following line:

    ```text /opt/zimbra/conf/custom_header theme={null}
    PREPEND X-AuthUser: ${authenticated_user}
    ```
  </Step>

  <Step title="Compile the hash database">
    Postfix requires a compiled hash database from the text file:

    ```bash theme={null}
    sudo postmap /opt/zimbra/conf/custom_header
    ```
  </Step>

  <Step title="Restart the Zimbra MTA">
    Apply all changes by restarting the Zimbra MTA service:

    ```bash theme={null}
    sudo /opt/zimbra/libexec/zmmtactl restart
    ```
  </Step>
</Steps>

## Resources

* [Zimbra Admin Guide — Zimbra Mail Transfer Agent](https://zimbra.github.io/documentation/zimbra-10/adminguide.html#_zimbra_mail_transfer_agent)

## Verify the configuration

<Steps>
  <Step title="Send a test email">
    Send a test email from a Zimbra user account to an address you control and confirm it is delivered successfully.
  </Step>

  <Step title="Check the X-AuthUser header">
    Inspect the headers of the received email and confirm that `X-AuthUser` is present and correctly populated with the authenticated user value.
  </Step>

  <Step title="Review the MailChannels Host Console">
    Log in to your [MailChannels Host Console](https://console.mailchannels.net) and navigate to **Outbound > Activity > Log Search**. In the transaction log, the `senderID` (`sid=`) field should contain your `${authenticated_user}` value in the third position.
  </Step>
</Steps>