<inputclass="md-option"data-md-color-media="(prefers-color-scheme: light)"data-md-color-scheme="default"data-md-color-primary="indigo"data-md-color-accent="indigo"aria-label="Switch to dark mode"type="radio"name="__palette"id="__palette_0">
<inputclass="md-option"data-md-color-media="(prefers-color-scheme: dark)"data-md-color-scheme="slate"data-md-color-primary="indigo"data-md-color-accent="blue"aria-label="Switch to light mode"type="radio"name="__palette"id="__palette_1">
<ahref="https://github.com/docker-mailserver/docker-mailserver/edit/master/docs/content/config/account-management/overview.md"title="Edit this page"class="md-content__button md-icon">
<ahref="https://github.com/docker-mailserver/docker-mailserver/raw/master/docs/content/config/account-management/overview.md"title="View source of this page"class="md-content__button md-icon">
<p>This page provides a technical reference for account management in DMS.</p>
<divclass="admonition note">
<pclass="admonition-title">Account provisioners and alternative authentication support</p>
<p>Each <ahref="../../environment/#account_provisioner"><code>ACCOUNT_PROVISIONER</code></a> has a separate page for configuration guidance and caveats:</p>
<p>The email address associated to an account creates a mailbox. This address is relevant:</p>
<ul>
<li>When DMS <strong>receives mail</strong> for that address as the recipient (<em>or an alias that resolves to it</em>), to identify which mailbox to deliver into.</li>
<li>With <strong>mail submission</strong>:<ul>
<li><code>SPOOF_PROTECTION=1</code><strong>restricts the sender address</strong> to the DMS account email address (<em>unless additional sender addresses have been permitted via supported config</em>).</li>
<li><code>SPOOF_PROTECTION=0</code> allows DMS accounts to <strong>use any sender address</strong> (<em>only a single DMS account is necessary to send mail with different sender addresses</em>).</li>
</ul>
</li>
</ul>
<hr/>
<p>For more details, see the <ahref="#technical-overview">Technical Overview</a> section.</p>
</details>
<detailsclass="note">
<summary>Support for multiple mail domains</summary>
<p>No extra configuration in DMS is required after provisioning an account with an email address.</p>
<ul>
<li>The DNS records for a domain should direct mail to DMS and allow DMS to send mail on behalf of that domain.</li>
<li>DMS does not need TLS certificates for your mail domains, only for the DMS FQDN (<em>the <code>hostname</code> setting</em>).</li>
</ul>
</details>
<detailsclass="warning">
<summary>Choosing a compatible email address</summary>
<p>An email address should conform to the standard <ahref="https://stackoverflow.com/questions/2049502/what-characters-are-allowed-in-an-email-address/2049510#2049510">permitted charset and format</a> (<code>local-part@domain-part</code>).</p>
<hr/>
<p>DMS has features that need to reserve special characters to work correctly. Ensure those characters are not present in email addresses you configure for DMS, otherwise disable / opt-out of the feature.</p>
<ul>
<li><ahref="#sub-addressing">Sub-addressing</a> is enabled by default with <code>+</code> as the <em>tag delimiter</em>. The tag can be changed, feature opt-out when the tag is explicitly unset.</li>
<li>As an alternative delivery address for a DMS account mailbox.</li>
<li>To redirect / forward to an external address outside of DMS like <code>@gmail.com</code>.</li>
</ul>
</div>
<detailsclass="abstract">
<summary>Technical Details (<em>Local vs Virtual aliases</em>)</summary>
<p>Aliases are managed through Postfix which supports <em>local</em> and <em>virtual</em> aliases:</p>
<ul>
<li><strong>Local aliases</strong> are for mail routed to the <ahref="https://www.postfix.org/local.8.html"><code>local</code> delivery agent</a> (see <ahref="https://www.postfix.org/aliases.5.html">associated alias config format</a>)<ul>
<li>You rarely need to configure this. It is used internally for system unix accounts belonging to the services running in DMS (<em>including <code>root</code></em>).</li>
<li><code>postmaster</code> may be a local alias to <code>root</code>, and <code>root</code> to a virtual alias or real email address.</li>
<li>Any mail sent through the <code>local</code> delivery agent will not be delivered to an inbox managed by Dovecot (<em>unless you have configured a local alias to redirect mail to a valid address or alias</em>).</li>
<li>The domain-part of an these aliases belongs to your DMS FQDN (<em><code>hostname: mail.example.com</code>, thus <code>user@mail.example.com</code></em>). Technically there is no domain-part at this point, that context is used when routing delivery, the local delivery agent only knows of the local-part (<em>an alias or unix account</em>).</li>
</ul>
</li>
<li><ahref="http://www.postfix.org/VIRTUAL_README.html#virtual_alias"><strong>Virtual aliases</strong></a> are for mail routed to the <ahref="https://www.postfix.org/virtual.8.html"><code>virtual</code> delivery agent</a> (see <ahref="https://www.postfix.org/virtual.5.html">associated alias config format</a>)<ul>
<li>When alias support in DMS is discussed without the context of being a local or virtual alias, it's likely the virtual kind (<em>but could also be agnostic</em>).</li>
<li>The domain-part of an these aliases belongs to a mail domain managed by DMS (<em>like <code>user@example.com</code></em>).</li>
</ul>
</li>
</ul>
<divclass="admonition tip">
<pclass="admonition-title">Verify alias resolves correctly</p>
<p>You can run <code>postmap -q <alias><table></code> in the container to verify an alias resolves to the expected target. If the target is also an alias, the command will not expand that alias to resolve the actual recipient(s).</p>
<p>For the <code>FILE</code> provisioner, an example would be: <code>postmap -q alias1@example.com /etc/postfix/virtual</code>. For the <code>LDAP</code> provisioner you'd need to adjust the table path.</p>
<p>As a side effect of the alias workaround for the <code>FILE</code> provisioner with this feature, aliases can be used for account login. This is not intentional.</p>
<p>Enables mail clients with the capability to query a mailbox for disk-space used and capacity limit.</p>
<ul>
<li>This feature is enabled by default, opt-out via <ahref="../../environment/#enable_quotas"><code>ENABLE_QUOTAS=0</code></a></li>
<li><strong>Not implemented</strong> for the LDAP provisioner (<em>PR welcome! View the <ahref="https://github.com/docker-mailserver/docker-mailserver/issues/2957">feature request for implementation advice</a></em>)</li>
</ul>
</div>
<detailsclass="tip">
<summary>How are quotas useful?</summary>
<p>Without quota limits for disk storage, a mailbox could fill up the available storage which would cause delivery failures to all mailboxes.</p>
<p>Quotas help by preventing that abuse, so that only a mailbox exceeding the assigned quota experiences a delivery failure instead of negatively impacting others (<em>provided disk space is available</em>).</p>
</details>
<detailsclass="abstract">
<summary>Technical Details</summary>
<p>The <ahref="https://github.com/docker-mailserver/docker-mailserver/pull/1469">Dovecot Quotas feature</a> is configured by enabling the <ahref="https://doc.dovecot.org/settings/plugin/imap-quota-plugin/">Dovecot <code>imap-quota</code> plugin</a> and using the <ahref="https://doc.dovecot.org/configuration_manual/quota/quota_count/#quota-backend-count"><code>count</code> quota backend</a>.</p>
<hr/>
<p><strong>Dovecot workaround for Postfix aliases</strong></p>
<p>When mail is delivered to DMS, Postfix will query Dovecot with the recipient(s) to verify quota has not been exceeded.</p>
<p>This allows early rejection of mail arriving to DMS, preventing a spammer from taking advantage of a <ahref="https://en.wikipedia.org/wiki/Backscatter_%28email%29">backscatter</a> source if the mail was accepted by Postfix, only to later be rejected by Dovecot for storage when the quota limit was already reached.</p>
<p>However, Postfix does not resolve aliases until after the incoming mail is accepted.</p>
<li>Postfix queries Dovecot (<em>a <ahref="https://github.com/docker-mailserver/docker-mailserver/issues/2091#issuecomment-954298788"><code>check_policy_service</code> restriction tied to the Dovecot <code>quota-status</code> service</a></em>) with the recipient (<em>the alias</em>).</li>
<li><code>dovecot: auth: passwd-file(alias@example.com): unknown user</code> is logged, Postfix is then informed that the recipient mailbox is not full even if it actually was (<em>since no such user exists in the Dovecot UserDB</em>).</li>
<li>However, when the real mailbox address that the alias would later resolve into does have a quota that exceeded the configured limit, Dovecot will refuse the mail delivery from Postfix which introduces a backscatter source for spammers.</li>
<p>As a <ahref="https://github.com/docker-mailserver/docker-mailserver/pull/2248#issuecomment-955088677">workaround to this problem with the <code>ENABLE_QUOTAS=1</code> feature</a>, DMS will add aliases as fake users into Dovecot UserDB (<em>that are configured with the same data as the real address the alias would resolve to, thus sharing the same mailbox location and quota limit</em>). This allows Postfix to properly be aware of an aliased mailbox having exceeded the allowed quota.</p>
<p><strong>NOTE:</strong> This workaround <strong>only supports</strong> aliases to a single target recipient of a real account address / mailbox.</p>
<ul>
<li>Additionally, aliases that resolve to another alias or to an external address would both fail the UserDB lookup, unable to determine if enough storage is available.</li>
<li>A proper fix would <ahref="https://github.com/docker-mailserver/docker-mailserver/pull/2248#issuecomment-953754532">implement a Postfix policy service</a> that could correctly resolve aliases to valid entries in the Dovecot UserDB, querying the <code>quota-status</code> service and returning that response to Postfix.</li>
<p><ahref="https://en.wikipedia.org/wiki/Email_address#Sub-addressing">Subaddressing</a> (<em>aka <strong>Plus Addressing</strong> or <strong>Address Tags</strong></em>) is a feature that allows you to receive mail to an address which includes a tag appended to the <code>local-part</code> of a valid account address.</p>
<ul>
<li>A subaddress has a tag delimiter (<em>default: <code>+</code></em>), followed by the tag: <code><local-part>+<tag>@<domain-part></code></li>
<li>The subaddress <code>user+github@example.com</code> would deliver mail to the same mailbox as <code>user@example.com</code>.</li>
<li>Tags are dynamic. Anything between the <code>+</code> and <code>@</code> is understood as the tag, no additional configuration required.</li>
<li>Only the first occurence of the tag delimiter is recognized. Any additional occurences become part of the tag value itself.</li>
<p>A common use-case is to use a unique tag for each service you register your email address with.</p>
<ul>
<li>Routing delivery to different folders in your mailbox based on the tag (<em>via a <ahref="../../advanced/mail-sieve/#subaddress-mailbox-routing">Sieve filter</a></em>).</li>
<li>Data leaks or bulk sales of email addresses.<ul>
<li>If spam / phishing mail you receive has not removed the tag, you will have better insight into where your address was compromised from.</li>
<li>When the expected tag is missing, this additionally helps identify bad actors. Especially when mail delivery is routed to subfolders by tag.</li>
</ul>
</li>
<li>For more use-cases, view the end of <ahref="https://www.codetwo.com/admins-blog/plus-addressing">this article</a>.</li>
</ul>
</details>
<detailsclass="tip">
<summary>Changing the tag delimiter</summary>
<p>Add <code>recipient_delimiter = +</code> to these config override files (<em>replacing <code>+</code> with your preferred delimiter</em>):</p>
<p>Follow the advice to change the tag delimiter, but instead set an empty value (<code>recipient_delimiter =</code>).</p>
</details>
<detailsclass="warning">
<summary>Only for receiving, not sending</summary>
<p>Do not attempt to send mail from these tagged addresses, they are not equivalent to aliases.</p>
<p>This feature is only intended to be used when a mail client sends to a DMS managed recipient address. While DMS does not restrict the sender address you choose to send mail from (<em>provided <code>SPOOF_PROTECTION</code> has not been enabled</em>), it is often <ahref="https://learn.microsoft.com/en-us/exchange/recipients-in-exchange-online/plus-addressing-in-exchange-online#using-plus-addresses">forbidden by mail services</a>.</p>
</details>
<detailsclass="abstract">
<summary>Technical Details</summary>
<p>The configured tag delimiter (<code>+</code>) allows both Postfix and Dovecot to recognize subaddresses. Without this feature configured, the subaddresses would be considered as separate mail accounts rather than routed to a common account address.</p>
<hr/>
<p>Internally DMS has the tag delimiter configured by:</p>
<ul>
<li>Applying the Postfix <code>main.cf</code> setting: <ahref="http://www.postfix.org/postconf.5.html#recipient_delimiter"><code>recipient_delimiter = +</code></a></li>
<li>Dovecot has the equivalent setting set as <code>+</code> by default: <ahref="https://doc.dovecot.org/settings/core/#core_setting-recipient_delimiter"><code>recipient_delimiter = +</code></a></li>
<p>This section provides insight for understanding how Postfix and Dovecot services are involved. It is intended as a reference for maintainers and contributors.</p>
<ul>
<li><strong>Postfix</strong> - Handles when mail is delivered (inbound) to DMS, or sent (outbound) from DMS.</li>
<li><strong>Dovecot</strong> - Manages access and storage for mail delivered to the DMS account mailboxes of your users.</li>
</ul>
</div>
<detailsclass="abstract">
<summary>Technical Details - Postfix (Inbound vs Outbound)</summary>
<p>Postfix needs to know how to handle inbound and outbound mail by asking these queries:</p>
<li>When <code>SPOOF_PROTECTION=1</code>, how should DMS restrict the sender address? (<em>eg: Users may only send mail from their associated mailbox address</em>)</li>
<p>Dovecot additionally handles authenticating user accounts for sending and retrieving mail:</p>
<ul>
<li>Over the ports for IMAP and POP3 connections (<em>110, 143, 993, 995</em>).</li>
<li>As the default configured SASL provider, which Postfix delegates user authentication through (<em>for the submission(s) ports 465 & 587</em>). Saslauthd can be configured as an alternative SASL provider.</li>
</ul>
<p>Dovecot splits all authentication lookups into two categories:</p>
<ul>
<li>A <ahref="https://doc.dovecot.org/configuration_manual/authentication/password_databases_passdb">PassDB</a> lookup most importantly authenticates the user. It may also provide any other necessary pre-login information.</li>
<li>A <ahref="https://doc.dovecot.org/configuration_manual/authentication/user_databases_userdb">UserDB</a> lookup retrieves post-login information specific to a user.</li>
<scriptid="__config"type="application/json">{"base":"../../..","features":["navigation.tabs","navigation.top","navigation.expand","navigation.instant","content.action.edit","content.action.view","content.code.annotate"],"search":"../../../assets/javascripts/workers/search.b8dbb3d2.min.js","translations":{"clipboard.copied":"Copied to clipboard","clipboard.copy":"Copy to clipboard","search.result.more.one":"1 more on this page","search.result.more.other":"# more on this page","search.result.none":"No matching documents","search.result.one":"1 matching document","search.result.other":"# matching documents","search.result.placeholder":"Type to start searching","search.result.term.missing":"Missing","select.version":"Select version"},"version":{"provider":"mike"}}</script>
