SYNTH MAIL

Install on a server

Real mail for your domain: Synth Mail receives mail from other servers on port 25 and sends yours straight to the recipients' servers, signed with DKIM. The HTTPS certificate comes from Let's Encrypt and is renewed by itself.

In the examples the domain is example.com and the server is mail.example.com — use your own names.

What you need

1. Two files

Create a folder with docker-compose.yml:

# Synth Mail on your own server: receives mail for your domain and sends it straight to the recipients' MX servers
# (port 25), DKIM-signed. Needs a server with a public address and port 25 open.
#
# Create .env next to this file:
#   MAIL_HOSTNAME=mail.example.com
#   MAIL_DOMAINS=example.com
#   ACME_EMAIL=you@example.com
#
# DNS before the first start (the certificate is issued over HTTP on MAIL_HOSTNAME):
#   A    mail.<domain>             -> public address of the server
#   PTR  public address            -> mail.<domain>        (hoster's panel: Reverse DNS)
#   MX   <domain>                  -> 10 mail.<domain>
#   TXT  <domain>                  -> "v=spf1 ip4:<public address> -all"
#   TXT  _dmarc.<domain>           -> "v=DMARC1; p=none; rua=mailto:postmaster@<domain>"
#   TXT  mail._domainkey.<domain>  -> printed in the "mail" log on the first start (DKIM key, kept in the data volume)
#
# Ports: 25 mail from other servers, 587 and 465 mail programs (SMTP), 993 mail programs (IMAP),
# 80 Let's Encrypt, 443 web client.
#
# First login: admin@<domain>, the password is in the "mail" log on the first start and in
# /app/data/initial-passwords.txt inside the container.
# Mail programs (SMTP, IMAP) use an app password, not the web password: Settings -> APP PASSWORDS.
# Registration is closed: new users only by the administrator (Admin panel); MAIL_REGISTRATION=true in .env opens it.
name: synth-mail

services:
  secrets-init:
    image: alpine:3.20
    restart: "no"
    command:
      - sh
      - -c
      - |
        umask 077
        for name in DB_PASSWORD JWT_SECRET; do
          [ -s /secrets/$$name ] || head -c 48 /dev/urandom | base64 | tr -dc 'A-Za-z0-9' > /secrets/$$name
        done
        chmod 644 /secrets/DB_PASSWORD /secrets/JWT_SECRET
    volumes:
      - secrets:/secrets

  # Let's Encrypt for MAIL_HOSTNAME: issued on the first start, renewed 30 days before the end (checked twice a day).
  # The deploy hook copies the pair to /tls (readable by the "mail" user 10001); the server reads it again within
  # a minute — no restart
  acme:
    image: goacme/lego:v5.5.2
    restart: unless-stopped
    ports:
      - "80:80"
    entrypoint:
      - sh
      - -c
      - |
        cat > /usr/local/bin/jb-deploy <<'EOF'
        #!/bin/sh
        set -e
        cp "$$LEGO_HOOK_CERT_PATH" /tls/cert.pem.new
        cp "$$LEGO_HOOK_CERT_KEY_PATH" /tls/key.pem.new
        chown 10001 /tls/cert.pem.new /tls/key.pem.new
        chmod 600 /tls/key.pem.new
        chmod 644 /tls/cert.pem.new
        mv /tls/key.pem.new /tls/key.pem
        mv /tls/cert.pem.new /tls/cert.pem
        echo "certificate for $$LEGO_HOOK_CERT_DOMAINS copied to /tls"
        EOF
        chmod 755 /usr/local/bin/jb-deploy
        while true; do
          /lego run --accept-tos --email "$$ACME_EMAIL" --domains "$$MAIL_HOSTNAME" --key-type EC256 \
            --http --http.address :80 --path /var/lib/lego --renew-days 30 --no-random-sleep \
            --deploy-hook /usr/local/bin/jb-deploy || echo "lego failed — next try in 1 hour"
          [ -s /tls/cert.pem ] && sleep 43200 || sleep 3600
        done
    environment:
      MAIL_HOSTNAME: ${MAIL_HOSTNAME:?set MAIL_HOSTNAME in .env}
      ACME_EMAIL: ${ACME_EMAIL:?set ACME_EMAIL in .env}
      LEGO_LOG_FORMAT: text
    volumes:
      - lego:/var/lib/lego
      - tls:/tls
    healthcheck:
      test: ["CMD-SHELL", "test -s /tls/cert.pem && test -s /tls/key.pem"]
      interval: 15s
      timeout: 5s
      start_period: 10m
      retries: 3
    mem_limit: 128m

  db:
    image: postgres:17
    restart: unless-stopped
    depends_on:
      secrets-init:
        condition: service_completed_successfully
    environment:
      POSTGRES_DB: mailserver
      POSTGRES_USER: mail
      POSTGRES_PASSWORD_FILE: /run/mail-secrets/DB_PASSWORD
    volumes:
      - pgdata:/var/lib/postgresql/data
      - secrets:/run/mail-secrets:ro
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U mail -d mailserver"]
      interval: 10s
      timeout: 5s
      retries: 10
    mem_limit: 256m

  mail:
    image: jambotron/synth-mail:${MAIL_IMAGE_TAG:-latest}
    pull_policy: always
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
      acme:
        condition: service_healthy   # waits for the first certificate
    ports:
      - "25:3025"
      - "587:3025"
      - "465:3465"
      - "993:3993"
      - "443:8443"   # web client + API over HTTPS
    environment:
      DB_HOST: db
      MAILSERVER_SECRETS_DIR: /run/mail-secrets
      MAIL_DOMAINS: ${MAIL_DOMAINS:?set MAIL_DOMAINS in .env}
      MAIL_HOSTNAME: ${MAIL_HOSTNAME:?set MAIL_HOSTNAME in .env}
      MAIL_TLS_CERT: /tls/cert.pem
      MAIL_TLS_KEY: /tls/key.pem
      SMTPS_PORT: "3465"
      IMAPS_PORT: "3993"
      HTTPS_PORT: "8443"
      DKIM_DOMAIN: ${MAIL_DOMAINS:?set MAIL_DOMAINS in .env}
      DKIM_SELECTOR: mail
      DKIM_KEYS_DIR: /app/data/dkim-keys
      MAIL_CATCH_ALL: ""
      MAIL_REGISTRATION: ${MAIL_REGISTRATION:-false}
      OUTBOUND_MODE: mx
      SMTP_AUTH_WITHOUT_TLS: "false"
      IMAP_AUTH_WITHOUT_TLS: "false"
      SPF_ENABLED: "true"
      DMARC_ENABLED: "true"
    volumes:
      - data:/app/data
      - secrets:/run/mail-secrets:ro
      - tls:/tls:ro
    mem_limit: 512m

volumes:
  secrets:
  pgdata:
  data:
  lego:
  tls:

and .env next to it:

MAIL_HOSTNAME=mail.example.com
MAIL_DOMAINS=example.com
ACME_EMAIL=you@example.com

MAIL_DOMAINS can list several domains: example.com,example.org. The first one is the main one — the first administrator admin@example.com lives there.

2. DNS records

mail.example.com must point at the server before the first start: the certificate is issued over HTTP on that name.

RecordNameValue
Amail.example.compublic address of the server
PTRpublic addressmail.example.com (in your provider's panel)
MXexample.com10 mail.example.com
TXTexample.comv=spf1 ip4:<public address> -all
TXT_dmarc.example.comv=DMARC1; p=none; rua=mailto:postmaster@example.com
TXTmail._domainkey.example.comfrom the log after the first start (step 3)

What each record does and how to tighten DMARC later: DNS records.

3. Start

docker compose up -d
docker compose logs mail

The first start waits for the certificate, usually less than a minute. The log of mail shows:

The password is also kept in the container: docker compose exec mail cat /app/data/initial-passwords.txt.

4. First login

Open https://mail.example.com, log in as admin with that password and change it in Settings → PASSWORD. Then:

  1. Add people in Admin panel → USERS (Users and mailboxes).
  2. Send a test mail to a Gmail or Outlook address and open it there: "Show original" should say SPF: PASS, DKIM: PASS, DMARC: PASS.
  3. Connect mail programs with app passwords (Mail programs).

Ports

PortWhat
25mail from other servers (and to them)
465, 587mail programs sending mail (SMTP, SSL/TLS and STARTTLS)
993mail programs reading mail (IMAP, SSL/TLS)
80Let's Encrypt
443web client

Something does not work