cplieger/docker-smtp-relay repository overview

⁠docker-smtp-relay

Point all your services at one container for outbound email; no per-app SMTP setup needed.

⁠What it does

Accepts email from services on your local network and forwards it through a real email provider (Gmail, AWS SES, Mailgun, etc.). Your apps just point at this container on port 25.

Example use cases:

• AWS SES: Set RELAY_HOST=email-smtp.us-east-1.amazonaws.com with your IAM SMTP credentials. Services on your LAN send to port 25; the relay handles SES authentication and TLS.
• Gmail: Set RELAY_HOST=smtp.gmail.com with an App Password. Paste the password as Google issues it, spaces included (wxyz abcd efgh aabb); quote it in YAML. Useful for sending alerts from devices that don't support OAuth2.
• Mailgun / Sendgrid / Generic SMTP: Any provider that accepts SMTP with STARTTLS on port 587 works out of the box.
• Multi-service self-hosted: NAS notifications, Grafana alerts, Paperless-ngx, Uptime Kuma, IoT devices; point them all at <host-ip>:25.

⁠Why this design

• Env-var config, not Postfix config files. Set a few environment variables and go; no main.cf templates to learn or maintain.
• Relay-only, not a full MTA. No local delivery, no mailbox management, no inbound routing. Does one thing well: accept mail and forward it upstream.
• Strict input validation. Every env var is validated before Postfix starts, so a bad value fails the container at boot instead of producing a misconfigured relay. See Security⁠ for the specific checks.
• Postfix as PID 1. Runs in foreground mode for proper signal handling; if it crashes, the container exits and Docker's restart policy recovers it cleanly.

⁠Pull

docker pull cplieger/docker-smtp-relay:latest

Also published to ghcr.io/cplieger/docker-smtp-relay with identical images and tags. Release versions are tagged vX.Y.Z alongside latest.

⁠Quick start

# Example compose for docker-smtp-relay. See the README for all configuration options and hardening.
services:
  smtp-relay:
    image: ghcr.io/cplieger/docker-smtp-relay:latest
    container_name: smtp-relay
    restart: unless-stopped

    environment:
      RELAY_HOST: "email-smtp.us-east-1.amazonaws.com"  # any SMTP provider hostname
      RELAY_LOGIN: "your-relay-login"
      RELAY_PASSWORD: "your-relay-password"
      RELAY_PORT: "587"  # 587 = STARTTLS, 465 = implicit TLS
      ACCEPTED_NETWORKS: "192.168.0.0/16"  # CIDRs that can relay mail

    ports:
      - "25:25"

    volumes:
      - "/path/to/smtp-relay-spool:/var/spool/postfix"  # persistent mail queue (replace host path)

⁠Documentation

• Full documentation⁠ — configuration, behavior, security
• Contributing⁠
• Releases and changelog⁠

⁠License

Apache-2.0. See LICENSE⁠.

The image carries the license text of every bundled component under /usr/share/licenses/. The Alpine packages in the image ship no license file upstream, so their license texts are kept under licenses/ in this repository and copied in.

It packages Postfix, which you may take under either the Eclipse Public License 2.0 or the IBM Public License 1.0, and Postfix's own LICENSE and TLS_LICENSE ship under /usr/share/licenses/postfix/. The exact version is pinned in the Dockerfile as POSTFIX_VERSION, with POSTFIX_SHA256 pinning the tarball the build fetches from https://high5.nl/mirrors/postfix-release/official/postfix-<version>.tar.gz (the fallback mirror serves the same path on http://ftp.porcupine.org); the upstream source repository is vdukhovni/postfix⁠. The build applies no patch files, and the only changes it makes to that source are the sed commands in the Dockerfile, so this repository at the commit that produced an image plus the pinned tarball are the complete build recipe for it.