Dovecot provides an SMTP submission service, also known as a Mail Submission Agent (MSA) (RFC 6409).
NOTE
Dovecot's submission server is NOT a full-featured SMTP server. It REQUIRES proxying to an external relay SMTP submission server to deliver non-local messages.
It is currently implemented as a proxy that acts as a front-end for any MTA, adding the necessary functionality required for a submission service: it adds the required AUTH (RFC 4954) support, avoiding the need to configure the MTA for SASL. Additionally, the client TLS layer is terminated at Dovecot (either with or without STARTTLS), so that all mail protocol certificates are handled solely by Dovecot and do not need to be configured in the MTA (although inter-server TLS encryption can be enabled if needed.)
More SMTP capabilities like CHUNKING (RFC 3030) and SIZE (RFC 1870) are supported, without requiring the backend MTA supporting these extensions.
Other capabilities like 8BITMIME (RFC 6152) and DSN (RFC 3461) currently require support from the backend/relay MTA.
The most notable feature that the proxy adds is the BURL capability (RFC 4468). The main application of that capability, together with IMAP server and URLAUTH (RFC 4467), is avoiding a duplicate upload of submitted e-mail messages. Normally the message is both sent through SMTP and uploaded to the Sent folder through IMAP. Using BURL, the client can first upload the message to IMAP and then use BURL to make the SMTP server fetch the message from IMAP for submission, thereby avoiding a second upload. Few clients currently support the BURL capability, but once it becomes available on the server side, client developers will at least have some incentive to provide support for this feature.
The submission service, when protocol submission is enabled, will listen to 587/tcp (STARTTLS) by default.
The following SMTP capabilities are supported by the Dovecot submission service:
Just add submission to the protocols= setting and configure the relay MTA server.
The submission service is a login service, just like IMAP, POP3 and ManageSieve, so clients are required to authenticate.
The same authentication configuration will apply to the submission service, unless you're doing protocol-specific things, in which case you may need to amend your configuration for the new protocol.
BURL support requires a working IMAP URLAUTH implementation. See imap_urlauth_host.
hostname| Default | <system's real hostname@domain.tld> |
|---|---|
| Value | string |
The hostname to be used in email messages sent out by the local delivery agent (such as the Message-ID: header), in LMTP replies, and as the hostname advertised by submission SMTP service.
submission_add_received_header| Default | yes |
|---|---|
| Value | boolean |
| Changes |
|
Controls if "Received:" header should be added to mails by the submission backend.
submission_client_workarounds| Default | [None] |
|---|---|
| Value | string |
Configures the list of active workarounds for Submission client bugs. The list is space-separated.
Supported workaround identifiers are:
implicit-auth-externalmailbox-for-pathwhitespace-before-pathsubmission_host| Default | [None] |
|---|---|
| Value | URL |
Use this SMTP submission host to send messages.
Overrides sendmail_path value, if set.
submission_logout_format| Default | in=%i out=%o |
|---|---|
| Value | string |
The SMTP Submission logout format string.
Variables supported, including Mail user variables:
| Variable Name | Description |
|---|---|
%{input}, %i |
Bytes read from client |
%{output}, %o |
Bytes sent to client |
%{command_count} |
Number of commands received from client |
%{reply_count} |
Number of replies sent to client |
%{transaction_id} |
ID of the current transaction, if any |
submission_max_mail_size| Default | 40M |
|---|---|
| Value | size |
The maximum message size accepted for relay.
This value is announced in the SMTP SIZE capability.
If empty, this value is either determined from the relay server or left unlimited if no limit is known; the relay MTA will reply with error if some unknown limit exists there, which will be passed back to the client.
submission_max_recipients| Default | [None] |
|---|---|
| Value | unsigned integer |
Maximum number of recipients accepted per connection.
0 means unlimited.
The Dovecot SMTP submission service directly proxies the mail transaction to the SMTP relay.
submission_relay_command_timeout| Default | 5mins |
|---|---|
| Value | time (milliseconds) |
Timeout for SMTP commands issued to the submission service's relay server.
The timeout is reset every time more data is being sent or received.
submission_relay_connect_timeout| Default | 30secs |
|---|---|
| Value | time (milliseconds) |
Timeout for connecting to and logging into the submission service's relay server.
submission_relay_host| Default | [None] |
|---|---|
| Value | string |
Host of the relay server (REQUIRED to provide the submission service).
submission_relay_master_user| Default | [None] |
|---|---|
| Value | string |
Master user name for authentication to the relay MTA if authentication is required.
submission_relay_max_idle_time| Default | 29mins |
|---|---|
| Value | time |
Submission relay max idle time for connection to relay MTA.
submission_relay_password| Default | [None] |
|---|---|
| Value | string |
Password for authentication to the relay MTA if authentication is required.
submission_relay_port| Default | 25 |
|---|---|
| Value | unsigned integer |
Value Range: <1-65535>
Port for the submission relay server.
submission_relay_rawlog_dir| Default | [None] |
|---|---|
| Value | string |
| See Also |
Write protocol logs for relay connection to this directory for debugging.
Mail user variables can be used.
submission_relay_ssl| Default | no |
|---|---|
| Value | string |
| Allowed Values | nosmtpsstarttls |
If enabled, SSL/TLS is used for the connection to the relay server.
Available values:
nosmtpsstarttlssubmission_relay_ssl_verify| Default | yes |
|---|---|
| Value | boolean |
If enabled, TLS certificate of the relay server must be verified.
submission_relay_trusted| Default | no |
|---|---|
| Value | boolean |
If enabled, the relay server is trusted.
Determines whether we try to send (Postfix-specific) XCLIENT data to the relay server (only if enabled).
submission_relay_user| Default | [None] |
|---|---|
| Value | string |
User name for authentication to the relay MTA if authentication is required.
Like IMAP and POP3, the Submission login service supports proxying to multiple backend Dovecot servers.
IMPORTANT
Please note that the login proxy described here is configured between two Dovecot servers (e.g. proxy frontend and mail storage backend). This is not the way to configure the relay connection between the Dovecot submission service and the MTA! That is configured using the relay settings described in the previous section. If you get this wrong, things will seem to work (at least to some extent), but the service provided by Dovecot will be effectively bypassed.
To listen on SMTPS port (465/tcp), add this to dovecot.conf:
service submission-login {
inet_listener submissions {
port = 465
ssl = yes
}
}The Dovecot submission service is structured very much like the imap and pop3 services, meaning that it has separate pre-login and post-login services called submission-login and submission respectively.
The pre-login service can be chrooted and can be devoid of most privileges and only serves to operate the TLS layer and perform authentication. This serves to isolate the sensitive SMTP functionality from unauthorized access, also when the frontend were compromised. Once authenticated, the connection is handed over to the post-login service.
The post-login service checks the validity of the SMTP transactions and forwards them on the fly to the backend MTA, while also translating or handling capabilities such as BURL and CHUNKING; e.g., when the backend MTA provides no support for these features. For the BURL capability, the post-login service has direct access to the user's mail storage.
Proxying for the submission service works identical to the imap and pop3 services. This means that the submission-login service proxies to another Dovecot backend instance that handles the subsequent relay to the MTA infrastructure. In this case there is proxying between two Dovecot instances and a relay from the Dovecot backend instance to a non-Dovecot backend MTA.
IMPORTANT
It is explicitly not supported to use submission-login to proxy directly to a backend MTA.
This would mean that after authentication the connection is proxied directly to the external non-Dovecot MTA, which will then completely handle the SMTP protocol exchange. Although authentication and TLS can still operate this way, the other features and additional protocol verification that Dovecot submission adds will be broken. Additionally, the submission-login service is likely to lie to the client about which SMTP capabilities are supported by the service, since the announced capabilities and those provided by the MTA will likely differ.