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
- A server with a public IP address and port 25 open. Many cloud providers block port 25 by default — ask them to open it. Without it no mail comes in and nothing goes out.
- Reverse DNS (PTR) for that address pointing to
mail.example.com, set in your provider's panel. Gmail and Outlook reject mail from addresses without it. - A domain where you can edit DNS records.
- Docker with Compose, about 1 GB of free memory, a few GB of disk for mail.
- Free ports: 25, 80, 443, 465, 587, 993.
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.
| Record | Name | Value |
|---|---|---|
| A | mail.example.com | public address of the server |
| PTR | public address | mail.example.com (in your provider's panel) |
| MX | example.com | 10 mail.example.com |
| TXT | example.com | v=spf1 ip4:<public address> -all |
| TXT | _dmarc.example.com | v=DMARC1; p=none; rua=mailto:postmaster@example.com |
| TXT | mail._domainkey.example.com | from 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:
User and mailbox created: admin@example.com — password: ...— the first administrator;DKIM DNS record — TXT mail._domainkey.example.com: v=DKIM1; ...— add this TXT record to DNS (one line per domain ofMAIL_DOMAINS).
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:
- Add people in Admin panel → USERS (Users and mailboxes).
- Send a test mail to a Gmail or Outlook address and open it there: "Show original" should say
SPF: PASS,DKIM: PASS,DMARC: PASS. - Connect mail programs with app passwords (Mail programs).
Ports
| Port | What |
|---|---|
| 25 | mail from other servers (and to them) |
| 465, 587 | mail programs sending mail (SMTP, SSL/TLS and STARTTLS) |
| 993 | mail programs reading mail (IMAP, SSL/TLS) |
| 80 | Let's Encrypt |
| 443 | web client |
Something does not work
- No certificate, the log waits:
mail.example.comdoes not point at the server yet, or port 80 is closed. - Mail does not come in: check the MX record and that port 25 is open from the internet
(
telnet mail.example.com 25from another network should show220 mail.example.com). - Gmail puts mail into spam or rejects it: check PTR, SPF and DKIM (the "Show original" view tells which one fails). A brand-new address needs a few days of normal mail to build reputation.