Sign inSign up

jambotron/synth-mail

By jambotron

•Updated 42 minutes ago

Mail server in one image: SMTP, IMAP, web mail, DKIM, SPF, DMARC. Free for any use.

Image
0

35

jambotron/synth-mail repository overview

⁠Synth Mail

A complete mail server in one image: SMTP, IMAP and a web client with a synthwave look. Receives mail for your domain and sends it straight to the recipients' servers, signed with DKIM. Checks SPF, DMARC and spam lists on incoming mail, protects logins from password guessing.

  • Users and mailboxes are separate. A user logs in; a mailbox has the mail. One user can have several personal mailboxes, a shared mailbox has several members.
  • Web client: folders, search, contacts, notes, six themes, high contrast, keyboard and screen reader support.
  • Mail programs (Thunderbird, phone mail) work over SMTP and IMAP with app passwords.
  • Admin panel: users and roles, mailboxes, a base set of mailboxes for every new user, limits.

Free for any use, including commercial. The source code is not published. See License⁠.

⁠Try it on your computer

No domain, no DNS: the web client and mail programs on your own machine, mail stays inside. Save this as docker-compose.yml and run docker compose up -d:

# Synth Mail on your own computer, to try it: web mail on http://localhost:8080, no mail to the internet.
name: synth-mail-local

services:
  db:
    image: postgres:17
    environment:
      POSTGRES_DB: mailserver
      POSTGRES_USER: mail
      POSTGRES_PASSWORD: local-db-password
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U mail -d mailserver"]
      interval: 5s
      retries: 20

  mail:
    image: jambotron/synth-mail:latest
    depends_on:
      db:
        condition: service_healthy
    ports:
      - "127.0.0.1:8080:8080"   # web mail
      - "127.0.0.1:587:3025"    # SMTP (STARTTLS)
      - "127.0.0.1:993:3993"    # IMAP (SSL/TLS)
    environment:
      DB_HOST: db
      DB_PASSWORD: local-db-password
      JWT_SECRET: local-jwt-secret-at-least-32-bytes-long
      MAIL_DOMAINS: example.test
      MAIL_HOSTNAME: localhost
      MAIL_ADMIN_PASSWORD: admin-password
      IMAPS_PORT: "3993"
      OUTBOUND_MODE: "off"
    volumes:
      - data:/app/data

volumes:
  pgdata:
  data:

Open http://localhost:8080⁠ and log in as [email protected] with admin-password. Without a real certificate the server makes a self-signed one, so mail programs will ask you to accept it.

⁠What you need

  • A server with a public IP address and port 25 open. Many cloud providers block port 25 by default: ask them to open it.
  • Reverse DNS (PTR) for that address, set in your provider's panel.
  • A domain where you can edit DNS records.
  • Docker with Compose. About 1 GB of free memory.

⁠Install

  1. Create a folder with two files.

    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
    #   [email protected]
    #
    # 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:
    

    .env (your names instead of the examples):

    MAIL_HOSTNAME=mail.example.com
    MAIL_DOMAINS=example.com
    [email protected]
    
  2. Set the DNS records. mail.example.com must point at the server before the first start: the HTTPS certificate is issued by Let's Encrypt 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:[email protected]
    TXTmail._domainkey.example.comfrom the log after the first start, see below
  3. Start:

    docker compose up -d
    docker compose logs mail
    

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

    • User and mailbox created: [email protected] — password: ... — the first administrator;
    • DKIM DNS record — TXT mail._domainkey.example.com: v=DKIM1; ... — add this record to DNS.
  4. Open https://mail.example.com, log in as [email protected] and change the password in Settings.

⁠Users and mailboxes

  • Admin panel → USERS: add people, give the role ADMIN or USER, block, set a new password.
  • Admin panel → BASE SET: mailboxes every new user gets, like {user} or {user}-monitor.
  • Admin panel → MAILBOXES: shared mailboxes and their members, who may write to a mailbox.
  • Admin panel → LIMITS: how many personal mailboxes a user may create.
  • Settings: a user's own mailboxes, theme, password, app passwords.

Registration is closed: users are added by an administrator. To open it, add MAIL_REGISTRATION=true to .env; at most 5 users can register from one IP address per day.

⁠Mail programs

The web password does not work in mail programs. In Settings → APP PASSWORDS create a password for one mailbox; the login is the mailbox address.

ServerPortSecurity
IMAPmail.example.com993SSL/TLS
SMTPmail.example.com465SSL/TLS
SMTPmail.example.com587STARTTLS

⁠Languages

English, Russian and Ukrainian are built in; each user picks one in the account menu. To add a language, take the template from https://<your server>/api/i18n/en, translate the values (keep the keys and {placeholders}, set @name), and save it as /app/data/i18n/<code>.json inside the data volume, for example de.json. No restart: it appears in the menu at once. Texts missing from the file stay in English.

⁠Update

docker compose pull
docker compose up -d

The database is updated on start. To stay on one version, set MAIL_IMAGE_TAG=0.1.0 in .env.

⁠Backup

Everything is in Docker volumes:

  • pgdata — users, mailboxes and letters;
  • data — attachments and the DKIM key (losing it means a new DNS record);
  • secrets — database password and the key of login sessions;
  • lego, tls — the certificate, issued again if lost.

Stop the stack (docker compose stop) and copy the volumes, or dump the database with pg_dump.

⁠Forgot the password

  • Another user's password: Admin panel → USERS → new password.
  • The first administrator's password, never changed: docker compose exec mail cat /app/data/initial-passwords.txt.

⁠License

The image is free to download, install and run for any purpose, including commercial use, on any number of servers. It may be redistributed only unmodified, free of charge and with the license. The full text is in the image: /app/licenses/LICENSE. Third-party components keep their own licenses: /app/licenses/.

Copyright (c) 2026 Yenushchenkov Oleksii.

Tag summary

Content type

Image

Digest

sha256:ac926b65e…

Size

156.2 MB

Last updated

42 minutes ago

docker pull jambotron/synth-mail