ngx_mail_module

IMAP, POP3 and SMTP proxy with HTTP-backed authentication

dynamic moduleBSD-2-Clausesource docs

Overview

ngx_mail_module turns nginx into a proxy for IMAP, POP3 and SMTP. A mail block holds one server per listening port, the protocol directive (or the well-known port) picks the protocol, and every client login is checked by an HTTP request to the authentication server named in auth_http. That server answers with Auth-Status, Auth-Server and Auth-Port headers, so it decides both whether the login is valid and which backend the session is proxied to.

ngx_mail_ssl_module adds TLS to the proxy: the ssl parameter of listen gives implicit TLS on ports such as 993 and 995, while starttls on or only controls the STLS and STARTTLS commands on plain ports. The auth_http request carries Client-IP, Auth-Login-Attempt and, since 1.7.11, Auth-SSL-* headers describing the client TLS session, and an Auth-Wait header in a failure response delays the next attempt instead of closing the connection. max_errors (1.21.0) closes a connection after 5 protocol errors by default.

It is an official nginx module that upstream does not build by default; it needs --with-mail and --with-mail_ssl_module. The n.wtf packages build it as a dynamic module shipped in libnginx-mod-mail, which the nginx-extras metapackage pulls in. The typical use is a single TLS front end for several mail stores, with the login check done by a small web service.

Key directives

listenAddress and port of the server; the ssl parameter enables implicit TLS and proxy_protocol accepts the PROXY protocol.
protocolSelects imap, pop3 or smtp; if omitted it is detected from ports 143/993, 110/995 and 25/587/465.
auth_httpURL of the HTTP authentication server that validates logins and names the backend server and port.
starttlsControls STLS and STARTTLS: off denies them, on allows them, only requires TLS before login; default off.
ssl_certificatePEM certificate for the mail server; may be repeated for RSA and ECDSA certificates since 1.11.0.
server_nameName used in the POP3/SMTP greeting, the CRAM-MD5 salt and the EHLO to the backend; default is the hostname.

Example

nginx.conf
mail { server_name mail.example.com; auth_http 127.0.0.1:9000/auth; ssl_certificate /etc/nginx/ssl/mail.example.com.crt; ssl_certificate_key /etc/nginx/ssl/mail.example.com.key; # IMAP with optional STARTTLS on 143, implicit TLS on 993 server { listen 143; protocol imap; starttls on; } server { listen 993 ssl; protocol imap; } # submission port, TLS required before login server { listen 587; protocol smtp; starttls only; } }

Availability

Ships as a dynamic module in libnginx-mod-mail, installed with nginx-extras. The package drops a load_module config into /etc/nginx/modules-enabled/, so it loads on start.