HTTPS and proxies · mailrust docs

mailrust either sits behind your web server or serves HTTPS on its own. Pick one per installation; you can switch later by changing the settings file and restarting the service.

Behind your web server

By default mailrust listens on 127.0.0.1:8420 and expects a web server in front of it to handle HTTPS. Change the address with MAILRUST_LISTEN in /etc/mailrust/mailrust.env.

nginx

server {
    listen 443 ssl;
    http2 on;
    server_name mail.example.com;

    # Your certificate, as for any other site.
    ssl_certificate     /etc/ssl/mail.example.com/fullchain.pem;
    ssl_certificate_key /etc/ssl/mail.example.com/privkey.pem;

    # Emails with attachments go up to 64 MB.
    client_max_body_size 64m;

    location / {
        proxy_pass http://127.0.0.1:8420;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 300s;
    }
}

Caddy

Caddy gets the certificate and passes the client's address by itself:

mail.example.com {
    reverse_proxy 127.0.0.1:8420
}

Hosting panels

In FastPanel, ISPmanager, cPanel or Plesk, create a site for the mail domain, turn on HTTPS there and set it to proxy to http://127.0.0.1:8420. Keep the Host header.

HTTPS by itself

Set the domain and mailrust answers on ports 443 and 80, gets a certificate from Let's Encrypt and renews it. Port 80 only redirects to HTTPS.

MAILRUST_DOMAIN=mail.example.com
MAILRUST_ACME_EMAIL=you@example.com

Put these lines in /etc/mailrust/mailrust.env and restart the service, or install with --domain and --email. Before that, point the domain's A and AAAA records at the server and make sure nothing else uses ports 80 and 443.

Setting	What it does	Default
`MAILRUST_DOMAIN`	Names to serve, separated by commas	none: proxy mode
`MAILRUST_ACME_EMAIL`	Contact for Let's Encrypt notices	none
`MAILRUST_HTTPS_LISTEN`	Address for HTTPS	`[::]:443`
`MAILRUST_HTTP_LISTEN`	Address for the redirect to HTTPS, or `off`	`[::]:80`
`MAILRUST_ACME_DIRECTORY`	Another ACME service, or `staging` to test with Let's Encrypt staging	Let's Encrypt
`MAILRUST_ACME_CA`	Root certificate of a private ACME service	none

Certificates are kept in the acme folder next to the database.

The visitor's real address

mailrust uses the visitor's address to slow down password guessing and to fill the audit log. It trusts headers such as X-Forwarded-For only from a proxy on the same machine. If your proxy runs elsewhere, in a container or on a load balancer, name it:

MAILRUST_TRUSTED_PROXIES=10.0.0.5,10.0.0.6

The word private trusts every internal network. From any other address the forwarding headers are removed and the connection's own address is used, so nobody can pretend to be someone else.

The installation's address

Links in emails, unsubscribe pages and the address that AI agents connect to all use the installation's address. You set it at the first run; an administrator can change it later under Admin → Installation address. MAILRUST_PUBLIC_URL in the settings file takes precedence over both.