cplieger/docker-smtp-relay repository overview

⁠docker-smtp-relay

docker-smtp-relay gives the apps and devices on your network one place to send email, and forwards it through your provider, such as AWS SES, Gmail or Mailgun. It only sends mail and holds no mailboxes.

⁠What it does

docker-smtp-relay lets every app on your network send email through one provider account:

• Your apps send to port 25 on your Docker host, with no login to set up in each app.
• Your provider login lives in one container, and by default mail leaves over TLS with certificate checks.
• Mail is queued and retried while your provider is unreachable.
• It checks each setting's format before it starts and names a wrong one in the log.
• It can limit which addresses your apps may send to.

⁠Who it is for

docker-smtp-relay is built for a home lab where a NAS, Grafana, Paperless-ngx, Uptime Kuma or IoT devices send alerts by email. Devices that cannot use your provider's login or TLS can still send.

You need an email provider account that accepts SMTP, with its server name, port and login. For Gmail, the login is an App Password. Keep port 25 on your own network.

Other projects suit other needs:

• Consider docker-mailserver⁠ if you want your own mailboxes. It is a full mail server with SMTP, IMAP, anti-spam and anti-virus.
• Consider Apprise⁠ if you want alerts in Telegram, Discord, Slack or Gotify. It sends to most popular notification services with one syntax.

docker-smtp-relay is free software under the Apache-2.0 license.

⁠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 docs/configuration.md and docs/hardening.md 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"  # your provider's SMTP server name
      RELAY_LOGIN: "${RELAY_LOGIN:?set RELAY_LOGIN in .env}"  # the SMTP username your provider gives you
      RELAY_PASSWORD: "${RELAY_PASSWORD:?set RELAY_PASSWORD in .env}"  # for Gmail, the App Password with its spaces
      RELAY_PORT: "587"  # 587 = STARTTLS, 465 = implicit TLS
      # For apps in other containers, add their Docker network range from "docker network inspect".
      ACCEPTED_NETWORKS: "192.168.0.0/16"  # the networks your apps send mail from

    ports:
      - "25:25"

    volumes:
      # Replace /path/to/smtp-relay-spool with a folder on your host before the first start.
      - "/path/to/smtp-relay-spool:/var/spool/postfix"  # keeps queued mail across restarts

⁠Documentation

• Full documentation⁠ — configuration, behavior, security
• Configuration⁠
• Security⁠
• How docker-smtp-relay works⁠
• Monitoring and alerts⁠
• 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.