Skip to main content
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.
Modifying Postfix configuration files can disrupt email delivery if done incorrectly. Back up /etc/postfix/main.cf and any related files before making changes.

​
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

1

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.
/etc/postfix/main.cf
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).
2

Create the SASL password file

Create /etc/postfix/sasl_passwd and add the following line, replacing the placeholder values with your actual MailChannels credentials.
/etc/postfix/sasl_passwd
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.
3

Generate the lookup table

Run postmap to compile the password file into a Berkeley database that Postfix can query at runtime.
4

Restrict file permissions

Limit read access to the password file and its compiled database to the root user only.
5

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:
/etc/postfix/main.cf
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.
/etc/postfix/header_checks
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.
6

Check and reload Postfix

Validate the configuration for syntax errors, then reload Postfix to apply all changes.
If reload is not sufficient (for example, after major structural changes), perform a full restart instead.

​
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.
1

Update main.cf

Comment out or remove the global relayhost line and add the following:
/etc/postfix/main.cf
2

Create the sender relay map

Create /etc/postfix/sender_relay. Use square-bracket notation around the host to prevent MX lookups.
3

Compile the map and reload

​
Optional: DKIM signing

Postfix does not sign DKIM natively. To sign outbound mail before it is handed off to MailChannels, run a signing milter such as OpenDKIM alongside Postfix. MailChannels does not modify the parts of a message covered by a DKIM signature, so signatures added before relay remain valid on delivery.
1

Install and configure the milter

Install OpenDKIM from your distribution’s package repository, generate a key pair for each sending domain, and configure /etc/opendkim.conf with your selector, domain, and key file location. See the OpenDKIM documentation for full instructions.
2

Publish the DNS record

Publish the public key as a TXT record at <selector>._domainkey.<yourdomain> in your DNS. OpenDKIM writes the record to a .txt file next to the generated key.
3

Attach the milter to Postfix

Add the milter socket to /etc/postfix/main.cf, then reload Postfix. Adjust the socket path to match the Socket setting in your opendkim.conf.
/etc/postfix/main.cf
4

Verify signing

Send a test message to an external mailbox and inspect the received headers. A successful signature produces an Authentication-Results header containing dkim=pass and a DKIM-Signature header with your selector and domain.
MailChannels’ managed DKIM signing is only available when sending through the Email API. It does not apply to SMTP relay traffic through smtp.mailchannels.net, so Postfix installations need to sign locally with a milter.

​
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.
/etc/postfix/main.cf