MailChannels: Setup Postfix – Help Center

Overview

This guide provides instructions on how to configure the Postfix Mail Transfer Agent (MTA) to relay outbound email through the MailChannels Outbound Filtering service. This involves setting up SMTP authentication using your MailChannels credentials, ensuring TLS encryption is used, optionally adding a sender identification header, and routing mail to the MailChannels servers.

Important: Modifying Postfix configuration files requires care. Incorrect settings can disrupt email delivery. Always back up your configuration files before making changes.

Audience

This guide is intended for server administrators managing servers running the Postfix MTA. Familiarity with editing Postfix configuration files (primarily main.cf and related map files) and basic command-line operations is assumed.

Prerequisites

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

Configuration Steps

Follow these steps to configure Postfix to relay outbound mail through MailChannels.

1. Configure Relay Host and Authentication

This step tells Postfix to send outgoing mail to MailChannels and how to authenticate using your credentials.

Edit the main Postfix configuration file: Open /etc/postfix/main.cf in a text editor.

Specify MailChannels as the relay host.
Enable SASL authentication for the SMTP client.
Specify the location of the SASL password file.
Enable TLS encryption (required by MailChannels).

Optionally, disable anonymous authentication mechanisms for added security.Add or modify the following lines:# /etc/postfix/main.cf

# 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
smtp_use_tls = yes
# Optional: For older Postfix versions or specific needs, you might use smtp_enforce_tls = yes
# smtp_tls_security_level = encrypt (alternative to smtp_use_tls=yes on newer Postfix)

Note: If outbound TCP port 25 is blocked on your network, you can use port 587 or 2525 instead (e.g., relayhost = smtp.mailchannels.net:587).
Create the SASL password file: Create a new file named /etc/postfix/sasl_passwd. Add the following line, replacing YOUR_USERNAME and YOUR_PASSWORD with your actual MailChannels SMTP credentials:
```
# /etc/postfix/sasl_passwd
smtp.mailchannels.net:25    YOUR_USERNAME:YOUR_PASSWORD
```
- Important: If you used a different port (e.g., 587) in relayhost, make sure to use the same host and port combination here (e.g., smtp.mailchannels.net:587 YOUR_USERNAME:YOUR_PASSWORD).
Generate the Postfix lookup table: Run the postmap command to create the database file (sasl_passwd.db) that Postfix uses:
```
sudo postmap /etc/postfix/sasl_passwd
```

Set secure permissions: Ensure only the root user can read the password file and its database map:

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

2. Add X-AuthUser Header (Recommended)

This header helps MailChannels identify the authenticated user or script responsible for sending an email, which is crucial for tracking and abuse mitigation.

Enable header checks in Postfix: Edit /etc/postfix/main.cf and add or modify the header_checks line:
```
# /etc/postfix/main.cf
header_checks = regexp:/etc/postfix/header_checks
```
Create the header checks file: Create a new file named /etc/postfix/header_checks. Add the following line. This regular expression looks for messages originating from authenticated users (sasl_username is populated) and prepends the X-AuthUser header with that username.
```
# /etc/postfix/header_checks
/^From:/ PREPEND X-AuthUser: ${sasl_username}
```
- Note: This assumes your Postfix setup correctly populates ${sasl_username} for authenticated outbound mail. This is typical when users authenticate via submission (port 587) or through SASL-enabled smtpd. If mail originates locally from scripts without direct SASL authentication, identifying the specific user might require different techniques (e.g., milters or custom submission wrappers).

3. Apply Configuration and Restart Postfix

Check the configuration for syntax errors (optional but recommended):
```
sudo postfix check
```
Reload Postfix to apply the changes:
```
sudo postfix reload
```
- If you encounter issues, you might need a full restart (sudo systemctl restart postfix or sudo service postfix restart), but reload is usually sufficient for main.cf changes.

Optional Configurations

These configurations are not strictly required for basic relaying but offer more control. Apply changes in /etc/postfix/main.cf or related files as indicated, then run sudo postmap <filename> (if creating/updating a map file) and sudo postfix reload.

Domain-Specific Routing

If you want only certain sender domains to relay through MailChannels, or if you want to exclude certain sender domains from relaying via MailChannels:

Remove or comment out the global relayhost line.
Add sender_dependent_relayhost_maps:
Modify main.cf:

# /etc/postfix/main.cf
# Comment out or remove: relayhost = smtp.mailchannels.net:25
sender_dependent_relayhost_maps = hash:/etc/postfix/sender_relay
# Keep the smtp_sasl_* and smtp_tls_* settings configured earlier

Create the /etc/postfix/sender_relay file:
- To relay ONLY specific domains: List the domains/addresses and map them to the MailChannels relay host.
  # /etc/postfix/sender_relay # Relay only these domains via MailChannels example.com [smtp.mailchannels.net]:25 another-domain.net [smtp.mailchannels.net]:25 user@specific.org [smtp.mailchannels.net]:25
- To EXCLUDE specific domains (relay everything else via MailChannels): You need a default relay and specific overrides. This requires transport_maps in addition to, or instead of, sender_dependent_relayhost_maps for more complex scenarios. A simpler approach using only sender_dependent_relayhost_maps might be to define the MailChannels relay for @ (default) and specify DUNNO or a direct delivery mechanism for excluded domains. Consult Postfix documentation for advanced routing. A basic exclusion example using sender_dependent_relayhost_maps:
  # /etc/postfix/sender_relay # Relay most via MailChannels, but exclude one domain exclude-this.com DUNNO # Or specify an alternative relay @ [smtp.mailchannels.net]:25 # Default for others
Generate the map file:
```
sudo postmap /etc/postfix/sender_relay
```
Reload Postfix:
```
sudo postfix reload
```

Queue Management

Adjust how long Postfix keeps messages in the queue before bouncing them.

Edit /etc/postfix/main.cf: Add or modify these parameters (values are examples, adjust as needed):

# /etc/postfix/main.cf

# Max time a message stays in the queue before bouncing as undeliverable
# Default is usually 5d (5 days)
maximal_queue_lifetime = 2d

# Max time a bounce message (delivery status notification) stays in the queue
# Default is usually 5d
bounce_queue_lifetime = 1d

Reload Postfix:
```
sudo postfix reload
```

Verify Configuration and Monitor

After configuring Postfix and reloading the service:

Send Test Emails: Send emails from an account or application hosted on your server to various external email addresses (e.g., Gmail, Outlook.com).
Check Mail Logs:
- Examine your Postfix mail logs (commonly /var/log/mail.log, /var/log/maillog, or managed via journald).
- Look for lines indicating successful delivery via relay=smtp.mailchannels.net. Check the status= field (e.g., status=sent).
- Check for any SASL authentication errors or TLS handshake issues.
Review MailChannels Console:
- Log in to your MailChannels Host Console.
- Navigate to the Activity > LogSearch section.
- Verify that your test messages appear and are being processed.
- Confirm the X-AuthUser header is present and contains the expected username. The 3rd field of your senderID or sid= header, contains the username value from your X-AuthUser header.
Test Bounces (Optional but Recommended): Send an email to a deliberately non-existent address at a remote domain to ensure bounces (Non-Delivery Reports) are generated and relayed correctly back through MailChannels.

Consistent monitoring of your Postfix logs and the MailChannels console is crucial to ensure smooth email delivery and to quickly identify any potential issues.