How to Configure a Relay Host

To send outgoing mail through another SMTP server (e.g. a provider or corporate server), configure a relay host.

Steps

1. Create credentials file

Create a file (e.g. sasl_passwd) with:

hostname username:password

Example for relay at mailpit on port 1025:

mailpit user1:password1

Set secure permissions:

chmod 600 sasl_passwd

2. Mount the file into the MTA container

In deploy/compose/mta.yaml (or your compose override), add a volume for the credentials file:

volumes:
  - data-tls:/etc/postfix/tls:ro
  - ./sasl_passwd:/etc/postfix/sasl_passwd_ext

Use the path where the MTA expects it (e.g. /etc/postfix/sasl_passwd_ext).

Do not mount the file read-only. The entrypoint runs chown, chmod, and postmap on it, which fail on a read-only mount and abort the container. postmap writes the lookup table next to the source file, so the directory containing it must be writable as well.

3. Set environment variables

In .env:

RELAYHOST=[hostname]:port
RELAY_PASSWD_FILE=/etc/postfix/sasl_passwd_ext

Example for Gmail:

RELAYHOST=[smtp.gmail.com]:587
RELAY_PASSWD_FILE=/etc/postfix/sasl_passwd_ext

Credentials file content for Gmail (use an app password):

smtp.gmail.com your-email@gmail.com:your-app-password

Example for Office 365:

RELAYHOST=[smtp.office365.com]:587
RELAY_PASSWD_FILE=/etc/postfix/sasl_passwd_ext

smtp.office365.com your-email@yourdomain.com:your-password

4. Restart the MTA

bin/production.sh up -d mta

(or docker-compose up -d mta).

Verification

Send a test message via webmail and check MTA logs for successful relay (e.g. status=sent).

For reference, see Environment variables reference (Relay section).