usernahme/postfix-relay repository overview

⁠postfix-relay

A containerised, weekly rebuilt version of bokysan/docker-postfix⁠.

This is not the official image. All credit for the Postfix configuration, scripts and documentation goes to the original project by bokysan⁠. This repository only builds the upstream sources automatically and publishes the result. The official images are boky/postfix⁠ and ghcr.io/bokysan/postfix.

⁠What it does

The container runs Postfix as a pure SMTP relay. Devices and applications in your network hand over their mail without logging in and without TLS. Postfix forwards it to your existing mail server, logging in there with your account.

Typical uses:

• Printers, scanners, cameras, NAS boxes, routers or Home Assistant that can only send mail without SMTP auth
• Applications in Docker that should share one central outgoing mail queue
• Sending through one provider account without storing its credentials on every device

It is meant for application and device mail, not for end-user mailboxes.

⁠Tags

• latest – most recent weekly build
• YYYY-MM-DD – build from that date, e.g. 2026-10-12

Only the six most recent dated tags are kept. Older ones are deleted automatically. Use latest, or pin a recent date if you need a fixed version.

⁠Build details

• Rebuilt every week from the latest stable upstream release
• Platform: linux/arm64 (e.g. Raspberry Pi 4/5 with a 64-bit OS)
• The upstream commit is stored in the image label org.opencontainers.image.revision
• One build fix is applied: sasl-build.sh fetches the pinned sasl-xoauth2 commit explicitly, because the upstream shallow clone can fail with unable to read tree. Nothing else is changed.

⁠Quick start

services:
  mailrelay:
    image: usernahme/postfix-relay:latest
    container_name: mailrelay
    restart: unless-stopped
    ports:
      - "25:587"
      - "587:587"
    environment:
      TZ: Europe/Berlin

      # Your mail server and login
      RELAYHOST: "[smtp.example.com]:587"
      RELAYHOST_USERNAME: "[email protected]"
      RELAYHOST_PASSWORD: "secret"

      # TLS to the provider (no "d"): enforce encryption
      POSTFIX_smtp_tls_security_level: "encrypt"
      # TLS for your devices (with "d"): plain SMTP in the LAN
      POSTFIX_smtpd_tls_security_level: "none"

      # Accepted sender domains, separated by spaces only
      ALLOWED_SENDER_DOMAINS: "example.com"
      # Your LAN plus the Docker networks
      POSTFIX_mynetworks: "127.0.0.0/8 172.16.0.0/12 192.168.1.0/24"

      POSTFIX_myhostname: "mailrelay.lan"
    volumes:
      - ./spool:/var/spool/postfix

Start it with docker compose up -d. Then configure your devices:

• SMTP server: IP of the Docker host
• Port: 25 or 587
• Login and encryption: none
• Sender address: an address from one of the allowed domains, e.g. [email protected]

⁠Ports

• 587/tcp – the only port Postfix listens on inside the container. Map it to any host port. Mapping host port 25 to it as well helps devices that can only use port 25. Both host ports share the same settings.

⁠Persistent data

Mount only what needs to survive the container being recreated (image update, changes to the compose file):

• /var/spool/postfix – required. The mail queue. If your provider is temporarily unreachable, mail waits here and is delivered later. Without this mount, queued mail is lost when the container is recreated.
• /etc/opendkim/keys and /var/lib/rspamd – only if you use DKIM signing. Otherwise DKIM_AUTOGENERATE creates new keys on every rebuild that no longer match your DNS record.

Not needed:

• Configuration – main.cf is generated from the environment variables on every start. Your settings live in the compose file.
• /etc/postfix – do not mount it. An empty host folder hides bundled files such as master.cf, and Postfix will no longer start.
• /var/lib/postfix – runtime data only, recreated automatically.

⁠Configuration

All settings are environment variables. For a normal relay to a provider, the first three sections are all you need.

⁠Sender domains (required)

• ALLOWED_SENDER_DOMAINS – domains the relay accepts as sender. Mail from any other domain is rejected with Recipient address rejected: Access denied. Postfix does not start without it. Separate the domains with spaces only. Commas or colons turn the whole list into one invalid entry, and every mail is rejected. Example: example.com example.org. Only list domains your provider lets you send from; usually that is just your own domain.
• ALLOW_EMPTY_SENDER_DOMAINS – set to true to run without a sender restriction. Only use this if access is limited in another way.

⁠Connection to your mail server

• RELAYHOST – the mail server that delivers your mail. Square brackets skip the MX lookup, which is what you want for a provider's SMTP server. Example: [smtp.example.com]:587
• RELAYHOST_USERNAME – login for the mail server, usually the full mail address.
• RELAYHOST_PASSWORD – password or app password.
• RELAYHOST_PASSWORD_FILE – alternative: path to a file containing the password, e.g. a Docker secret. Do not set both.
• POSTFIX_smtp_tls_security_level – TLS towards the mail server. may (default) uses TLS if offered, encrypt enforces it. Use encrypt whenever a password is sent.
• POSTFIX_smtp_tls_wrappermode – set to yes if your provider uses port 465 instead of 587.
• SASL_RELAYHOST – only needed if the host name used for login differs from RELAYHOST.

⁠Access from your devices

• POSTFIX_mynetworks – networks that may send without login. Limit this to your LAN, but keep 172.16.0.0/12: connections from the Docker host itself and from other containers arrive from a Docker network such as 172.17.0.1, not from a LAN address. Default: 127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16
• POSTFIX_smtpd_tls_security_level – TLS for devices sending to the relay (with "d"). The default may offers STARTTLS with a self-signed certificate, which many devices try and then fail on. Set it to none for plain SMTP in the LAN.
• SMTPD_SASL_USERS – optional: require devices to log in after all. Comma-separated user@domain:password pairs.

⁠Identity and limits

• POSTFIX_myhostname – name of the relay in logs and mail headers. Default: the container ID. Example: mailrelay.lan
• POSTFIX_message_size_limit – maximum message size in bytes. Set it to your provider's limit, so oversized mail is rejected right away instead of staying in the queue. Default: 0 (unlimited). Example: 26214400 (25 MB)
• MASQUERADED_DOMAINS – rewrites sender addresses from subdomains to the main domain, e.g. [email protected] becomes [email protected].
• AUTOSET_HOSTNAME – set to 1 to determine the host name via reverse DNS of the public IP. Mainly useful when sending without a relay host.

⁠Logging

• TZ – time zone for logs and mail headers, e.g. Europe/Berlin
• LOG_FORMAT – plain (default) or json
• INBOUND_DEBUGGING – 1 for detailed logs of incoming connections
• ANONYMIZE_EMAILS – masks mail addresses in the logs: smart, paranoid or hash?salt=...

⁠DKIM signing (optional)

Only needed if you send directly or your mail server does not sign your mail. Most providers sign automatically.

• DKIM_AUTOGENERATE – true creates keys on first start. Mount the key folders, see Persistent data.
• DKIM_SELECTOR – selector, default mail. Per domain: default,example.org=postfix
• DKIM_BACKEND – rspamd (default) or opendkim (deprecated)

⁠Advanced

• POSTFIX_<option> – sets any Postfix option⁠. An empty value removes it.
• SMTP_HEADER_CHECKS – 1 enables the bundled header checks.
• XOAUTH2_* – OAuth2 login instead of a password (Gmail, Microsoft 365). See the upstream documentation.

The upstream README⁠ remains the complete reference for all options, Helm charts, metrics and custom init scripts.

⁠Provider examples

Port 587 with STARTTLS (most providers):

RELAYHOST=[smtp.example.com]:587
[email protected]
RELAYHOST_PASSWORD=secret
POSTFIX_smtp_tls_security_level=encrypt
ALLOWED_SENDER_DOMAINS=example.com

Port 465 with implicit TLS:

RELAYHOST=[smtp.example.com]:465
POSTFIX_smtp_tls_wrappermode=yes
POSTFIX_smtp_tls_security_level=encrypt

Gmail with an app password:

RELAYHOST=[smtp.gmail.com]:587
[email protected]
RELAYHOST_PASSWORD=your-app-password
ALLOWED_SENDER_DOMAINS=gmail.com

⁠Testing and troubleshooting

Watch the log while a device sends a test mail:

docker logs -f mailrelay

Check that the relay offers plain SMTP (the answer must not contain 250-STARTTLS):

printf 'EHLO test\r\nQUIT\r\n' | nc <host-ip> 25

Common messages:

• Recipient address rejected: Access denied – the sender domain is not accepted. Check the startup line Setting up allowed SENDER domains:. The domains must appear there separated by spaces.
• Client host rejected: Access denied – the sending IP is not in POSTFIX_mynetworks. The log shows the IP the container sees, e.g. connect from unknown[172.17.0.1].
• Device reports a TLS or certificate error – set POSTFIX_smtpd_tls_security_level: "none".
• Mail accepted but never arrives – look for status=deferred or status=bounced. Usually the provider rejects the login or the sender address. Most providers only accept senders that match the login account.
• error: open database /etc/aliases.lmdb – harmless for a relay.

⁠Security

• Never expose the port to the internet. Anyone in POSTFIX_mynetworks can send mail through your account without logging in.
• Keep POSTFIX_mynetworks limited to your own networks.
• Prefer RELAYHOST_PASSWORD_FILE with a Docker secret over a plain-text password.

⁠Issues and license

Problems with Postfix, its options or the image contents belong in the upstream issue tracker⁠. Problems that only affect this rebuild (tags, schedule, build fix) can be reported here.

The original project is published under the MIT license⁠, copyright by its authors. This rebuild uses it under the same terms.