# Mail Module The core mail module implements basic functionality for a mail proxy server: this includes support for SMTP, IMAP, and POP3 protocols, configuring server blocks, mail request routing, user authentication, and SSL/TLS support for securing mail connections. The other modules in this section extend this functionality, allowing you to flexibly configure and optimize the mail server for various scenarios and requirements. When [building from source](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), this module isn't built by default; it should be enabled with the `--with-mail` [build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure). In packages and images from [our repos](https://en.angie.software//angie/docs/installation/index.md#install-packages), the module is included in the build. ## Configuration Example ```nginx worker_processes auto; error_log /var/log/angie/error.log info; events { worker_connections 1024; } mail { server_name mail.example.com; auth_http localhost:9000/cgi-bin/auth.cgi; imap_capabilities IMAP4rev1 UIDPLUS IDLE LITERAL+ QUOTA; pop3_auth plain apop cram-md5; pop3_capabilities LAST TOP USER PIPELINING UIDL; smtp_auth login plain cram-md5; smtp_capabilities "SIZE 10485760" ENHANCEDSTATUSCODES 8BITMIME DSN; xclient off; server { listen 25; protocol smtp; } server { listen 110; protocol pop3; proxy_pass_error_message on; } server { listen 143; protocol imap; } server { listen 587; protocol smtp; } } ``` ## Directives ### listen | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `listen` address[:port] [`ssl`] [`proxy_protocol`] [`backlog=`number] [`rcvbuf=`size] [`sndbuf=`size] [`bind`] [`ipv6only=``on` | `off`] [`reuseport`] [`so_keepalive=`on|off|[`keepidle`]:[`keepintvl`]:[`keepcnt`]]; | |------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Default | — | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | server | Sets the address and port for the socket on which the server will accept connections. It is possible to specify just the port, and Angie will listen on all available IPv4 interfaces (and IPv6, if enabled). The address can also be a hostname, for example: ```nginx listen 127.0.0.1:110; listen *:110; listen 110; # same as *:110 listen localhost:110; ``` IPv6 addresses are specified in square brackets: ```nginx listen [::1]:110; listen [::]:110; ``` UNIX-domain sockets are specified with the `unix:` prefix: ```nginx listen unix:/var/run/angie.sock; ``` #### NOTE Different servers must listen on different address:port pairs. | `ssl` | specifies that all connections accepted on this port should work in SSL mode. | |------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `proxy_protocol` | specifies that all connections accepted on this port should use
the PROXY protocol. Obtained information is passed to the
[authentication server](https://en.angie.software//angie/docs/configuration/modules/mail/mail_auth_http.md#mail-auth-http) and can be used to
[change the client address](https://en.angie.software//angie/docs/configuration/modules/mail/mail_realip.md#mail-realip). | The `listen` directive can have several additional parameters specific to socket-related system calls. | `backlog=`number | sets the backlog parameter in the `listen()` call that limits the
maximum length for the queue of pending connections. By default,
backlog is set to -1 on FreeBSD, DragonFly BSD, and macOS, and
to 511 on other platforms. | |-----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `rcvbuf=`size | sets the receive buffer size (the SO_RCVBUF option) for the listening socket. | | `sndbuf=`size | sets the send buffer size (the SO_SNDBUF option) for the listening socket. | | `bind` | instructs to make a separate `bind()` call for a
given address:port pair. The fact is that if there are several
`listen` directives with the same port but different addresses,
and one of the `listen` directives listens on all addresses for the
given port (\*:port), Angie will `bind()` only to \*:port.
It should be noted that the `getsockname()` system call will be
made in this case to determine the address that accepted the connection.
If the backlog, rcvbuf, sndbuf, ipv6only,
reuseport, or so_keepalive parameters are used then for a
given address:port pair a separate `bind()` call will always be
made. | | `ipv6only=on` | `off` | determines (via the IPV6_V6ONLY socket option) whether an IPv6 socket listening on a wildcard address [::] will accept only IPv6 connections or both IPv6 and IPv4 connections. This parameter is turned on by default. It can only be set once on start. | | `multipath` | enables accepting connections via [Multipath TCP](https://en.wikipedia.org/wiki/Multipath_TCP) (MPTCP),
supported in Linux kernel version 5.6 and later. | `so_keepalive=on` | `off` | [`keepidle`]:[`keepintvl`]:[`keepcnt`] Configures the "TCP keepalive" behavior for the listening socket. | `''` | if this parameter is omitted then the operating system's settings will be in effect for the socket | |--------|------------------------------------------------------------------------------------------------------| | `on` | the SO_KEEPALIVE option is turned on for the socket | | `off` | the SO_KEEPALIVE option is turned off for the socket | Some operating systems support setting of TCP keepalive parameters on a per-socket basis using the `TCP_KEEPIDLE`, `TCP_KEEPINTVL`, and `TCP_KEEPCNT` socket options. On such systems, they can be configured using the `keepidle`, `keepintvl`, and `keepcnt` parameters. One or two parameters may be omitted, in which case the system default setting for the corresponding socket option will be in effect. For example, ```nginx so_keepalive=30m::10 ``` will set the idle timeout (`TCP_KEEPIDLE`) to 30 minutes, leave the probe interval (`TCP_KEEPINTVL`) at its system default, and set the probes count (`TCP_KEEPCNT`) to 10 probes. Different servers must listen on different address:port pairs. ### mail | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `mail` { ... } | |------------------------------------------------------------------------------------------|------------------| | Default | — | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | main | Provides the configuration file context in which the mail server directives are specified. ### max_commands | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `max_commands` number; | |------------------------------------------------------------------------------------------|--------------------------| | Default | `max_commands 1000;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server | Sets the maximum number of commands issued during authentication to enhance protection against DoS attacks. ### max_errors | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `max_errors` number; | |------------------------------------------------------------------------------------------|------------------------| | Default | `max_errors 5;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server | Sets the number of protocol errors after which the connection is closed. ### protocol | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `protocol` imap | pop3 | smtp; | |------------------------------------------------------------------------------------------|----------------------------------| | Default | — | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | server | Sets the protocol for a proxied server. Supported protocols are [IMAP](https://en.angie.software//angie/docs/configuration/modules/mail/mail_imap.md#mail-imap), [POP3](https://en.angie.software//angie/docs/configuration/modules/mail/mail_pop3.md#mail-pop3), and [SMTP](https://en.angie.software//angie/docs/configuration/modules/mail/mail_smtp.md#mail-smtp). If the directive is not set, the protocol can be detected automatically based on the well-known port specified in the `listen` directive: ```console imap: 143, 993 pop3: 110, 995 smtp: 25, 587, 465 ``` When [building from source](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild), unnecessary protocols can be disabled using the `‑‑without‑mail_imap_module`, `‑‑without‑mail_pop3_module`, and `‑‑without‑mail_smtp_module` [build options](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure). ### resolver | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `resolver` address ... [`valid=`time] [`ipv4=``on` | `off`] [`ipv6=``on` | `off`] [`status_zone=`zone] | `off`; | |------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------| | Default | `resolver off;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server | Configures name servers used to find the client's hostname to pass it to the [authentication server](https://en.angie.software//angie/docs/configuration/modules/mail/mail_auth_http.md#mail-auth-http), and in the [XCLIENT](https://en.angie.software//angie/docs/configuration/modules/mail/mail_proxy.md#m-xclient) command when proxying SMTP. For example: ```nginx resolver 127.0.0.53 [::1]:5353; ``` The special value `off` disables resolving of the client hostname and cancels an inherited directive value. The address can be specified as a domain name or IP address, with an optional port. If port is not specified, the port 53 is used. Name servers are queried in a round-robin fashion. #### NOTE Prefer a local trusted resolver such as `127.0.0.53` (systemd-resolved) over a public one (e.g. `8.8.8.8`). Public resolvers expose DNS queries to third parties and increase susceptibility to cache-poisoning attacks. #### NOTE The directive value is inherited by nested blocks and can be overridden in them if necessary. Within a single block, the directive can only be specified once. If it is repeated, the last definition takes effect. By default, Angie caches answers using the TTL value of a response. If the `resolver` directive is not specified and no dynamic DNS queries are performed (for example, when using fixed names in [Proxy](https://en.angie.software//angie/docs/configuration/modules/mail/mail_proxy.md#mail-proxy) without variables), specifying a resolver is not required: names will be resolved at startup using the system resolver. The optional `valid` parameter allows overriding this: | `valid` | *optional* parameter allows overriding cached entry validity | |-----------|----------------------------------------------------------------| ```nginx resolver 127.0.0.53 [::1]:5353 valid=30s; ``` By default, Angie will look up both IPv4 and IPv6 addresses while resolving. | `ipv4=off` | disables looking up of IPv4 addresses | |---------------|-----------------------------------------------------------------------------------------------------------------------| | `ipv6=off` | disables looking up of IPv6 addresses | | `status_zone` | *optional* parameter, enables collection of information about DNS server requests and responses in the specified zone | ### resolver_timeout | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `resolver_timeout` time; | |------------------------------------------------------------------------------------------|----------------------------| | Default | `resolver_timeout 30s;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server | Sets a timeout for name resolution, for example: ```nginx resolver_timeout 5s; ``` ### server | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `server` { ... } | |------------------------------------------------------------------------------------------|--------------------| | Default | — | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | mail | Sets the configuration for a server. ### server_name | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `server_name` name; | |------------------------------------------------------------------------------------------|-------------------------| | Default | `server_name hostname`; | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server | Sets the server name that is used: * in the initial POP3/SMTP server greeting; * in the salt during the SASL CRAM-MD5 authentication; * in the EHLO command when connecting to the SMTP backend, if the passing of the [XCLIENT](https://en.angie.software//angie/docs/configuration/modules/mail/mail_proxy.md#m-xclient) command is enabled. If the directive is not specified, the machine's hostname is used. ### timeout | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `timeout` time; | |------------------------------------------------------------------------------------------|-------------------| | Default | `timeout 60s;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server | Sets the timeout that is used before proxying to the backend starts.