🌐 Domain & TLS Setup

Step 1: Configure DNS Records

First, set up the following DNS records in your domain management panel:

# A record — point hostname to server IP (required before install)
chat.example.org. A 203.0.113.50

# MX record — mail domain → hostname (SMTP fallback federation)
example.org. MX 10 chat.example.org.

Optional for SMTP deliverability (not required for chatmail HTTP federation between relays): SPF, DKIM TXT at default._domainkey, and DMARC. install --domain obtains TLS and generates DKIM signing keys; you publish DNS TXT records yourself. See the operator guide DNS and Mail Authentication in the project docs.

Note: After setting up records, it may take 5 minutes to 24 hours to propagate. To check immediately: dig +short chat.example.org A and curl -sI https://chat.example.org/mxdeliv

Step 2: Choose TLS Mode

Madmail supports four TLS modes. The table below shows the differences:

Mode Challenge DNS API Port 80 Use Case
autocert HTTP-01 No Required Production server
acme DNS-01 Yes No Server behind firewall
file — — — Existing certificate
self_signed — — — Testing & development

🏆 autocert mode Recommended

Install (madmail Install)
sudo madmail install \
  --domain chat.example.org \
  --tls-mode autocert \
  --acme-email [email protected] \
  --enable-chatmail \
  --non-interactive

How it works:

  1. Madmail starts an HTTP server on port 80 for the ACME challenge
  2. Let's Encrypt sends a request to port 80 to verify domain ownership
  3. A certificate is issued (valid for 90 days, auto-renewed)
  4. Certificates are stored in /var/lib/madmail/autocert/

In the configuration file (madmail.conf):

madmail.conf
tls {
    loader autocert {
        hostname chat.example.org
        email [email protected]
        cache_dir /var/lib/madmail/autocert
        agreed
    }
}

🔐 acme mode (DNS-01) Advanced

Install (Madmail Install)
sudo madmail install \
  --domain chat.example.org \
  --tls-mode acme \
  --acme-email [email protected] \
  --acme-dns-provider cloudflare \
  --acme-dns-token "YOUR_CLOUDFLARE_TOKEN" \
  --enable-chatmail \
  --non-interactive

Supported DNS providers: cloudflare, gandi, digitalocean, vultr, hetzner, route53

📄 file mode (Existing certificate)

Install (Madmail Install)
sudo madmail install \
  --domain chat.example.org \
  --tls-mode file \
  --cert-path /etc/letsencrypt/live/chat.example.org/fullchain.pem \
  --key-path /etc/letsencrypt/live/chat.example.org/privkey.pem \
  --enable-chatmail

Configuration file format:

tls file /path/to/fullchain.pem /path/to/privkey.pem
Renewal: Set up a certbot hook to restart madmail after renewal:
systemctl restart madmail

🧪 self_signed mode (Testing)

Install (madmail Install)
sudo madmail install \
  --simple --ip YOUR_SERVER_IP \
  --tls-mode self_signed \
  --turn-off-tls

Certificates are stored in /var/lib/madmail/certs/ and reused on subsequent restarts.

Step 3: Verify Certificate

After setup, verify your certificate with this command:

echo | openssl s_client -connect chat.example.org:443 \ -servername chat.example.org 2>&1 | \ openssl x509 -noout -subject -issuer -dates

Expected output:

subject=CN=chat.example.org issuer=C=US, O=Let's Encrypt, CN=E7 notBefore=Feb 21 15:41:47 2026 GMT notAfter=May 22 15:41:46 2026 GMT

Switching TLS Mode

From self_signed to autocert

Remove old certificates
sudo rm /var/lib/madmail/certs/fullchain.pem /var/lib/madmail/certs/privkey.pem
Reinstall with autocert
sudo madmail install \
  --domain chat.example.org \
  --tls-mode autocert \
  --acme-email [email protected] \
  --enable-chatmail \
  --non-interactive
Final restart
sudo systemctl restart madmail

Troubleshooting

🔑 file: Permission denied error?

Run the following commands to fix file ownership and permissions:

Fix Permissions
sudo chown root:madmail /path/to/cert.pem /path/to/key.pem
sudo chmod 640 /path/to/cert.pem /path/to/key.pem
🛡️ Security Notes: