docs(refactor): Sub-addressing section

Much better docs on the sub-addressing feature supported by Postfix and Dovecot, along with the guidance with usage in Sieve.

docs/content/config/account-management/overview.md

@@ -10,7 +10,7 @@ An account has an email address `local-part@domain-part`.
 
 ### Aliases
 
-You may read [Postfix's documentation on virtual aliases][postfix-docs-alias] first.
+You may read [Postfix's documentation on virtual aliases][postfix-docs::virtual-alias] first.
 
 An alias is a full email address that will either be:
 
@@ -21,22 +21,55 @@ Known issues
 Alias and Account names cannot overlap
 Wildcard and need to alias each real account.. (no longer supported?)
 
-### Sub-addressing (aka Plus Addressing / Extension Tags)
+### Sub-addressing
 
-Postfix supports so-called address tags, in the form of plus (+) tags - i.e. `address+tag@example.com` will end up at `address@example.com`.
+!!! info
 
-This is configured by default and the (configurable!) separator is set to `+`. For more info, see [Postfix's official documentation][postfix-docs-extension-delimiters].
+    [Subaddressing][wikipedia::subaddressing] (_aka Plus Addressing or Address Tags_) is a feature that allows you to receive mail to an address which includes a tag appended to the `local-part` of a valid account address.
 
-!!! note
+    - A subaddress has a tag delimiter (default: `+`), followed by the tag: `<local-part>+<tag>@<domain-part>`
+    - The subaddress `user+github@example.com` would deliver mail to the same mailbox as `user@example.com`.
+    - Tags are dynamic. Anything between the `+` and `@` is understood as the tag, no additional configuration required.
+    - Only the first occurence of the tag delimiter is recognized. Any additional occurences become part of the tag value itself.
 
-    If you do decide to change the configurable separator, you must add the same line to *both* `docker-data/dms/config/postfix-main.cf` and `docker-data/dms/config/dovecot.cf`, because Dovecot is acting as the delivery agent. For example, to switch to `-`, add:
+!!! tip "When is subaddressing useful?"
 
-    ```cf
+    A common use-case is to use a unique tag for each service you register your email address with.
-    recipient_delimiter = -
+
-    ```
+    - Routing delivery to different folders in your mailbox based on the tag (_via a [Sieve filter][docs::sieve::subaddressing]_).
+    - Data leaks or bulk sales of email addresses.
+        - If spam / phishing mail you receive has not removed the tag, you will have better insight into where your address was compromised from.
+        - When the expected tag is missing, this additionally helps identify bad actors. Especially when mail delivery is routed to subfolders by tag.
+    - For more use-cases, view the end of [this article][web::subaddress-use-cases].
+
+??? tip "Changing the tag delimiter"
+
+    Add `recipient_delimiter = +` to these config override files (_replacing `+` with your preferred delimiter_):
+
+    - Postfix: `docker-data/dms/config/postfix-main.cf`
+    - Dovecot: `docker-data/dms/config/dovecot.cf`
+
+??? tip "Opt-out of subaddressing"
+
+    Follow the advice to change the tag delimiter, but instead set an empty value (`recipient_delimiter =`).
+
+??? warning "Only for receiving, not sending"
+
+    Do not attempt to send mail from these tagged addresses, they are not equivalent to aliases.
+
+    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 (_provided `SPOOF_PROTECTION` has not been enabled_), it is often [forbidden by mail services][ms-exchange-docs::limitations].
+
+??? abstract "Technical Details"
+
+    The configured tag delimiter (`+`) 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.
+
+    ---
+
+    Internally DMS has the tag delimiter configured by:
+
+    - Applying the Postfix `main.cf` setting: [`recipient_delimiter = +`][postfix-docs::recipient-delimiter]
+    - Dovecot has the equivalent setting set as `+` by default: [`recipient_delimiter = +`][dovecot-docs::config::recipient-delimiter]
 
-[postfix-docs-alias]: http://www.postfix.org/VIRTUAL_README.html#virtual_alias
-[postfix-docs-extension-delimiters]: http://www.postfix.org/postconf.5.html#recipient_delimiter
 
 ### Quotas
 
@@ -76,3 +109,12 @@ default feature enabled, dovecot creates dummy accounts to workaround alias limi
 
     - A [PassDB][dovecot::docs::passdb] lookup most importantly authenticates the user. It may also provide any other necessary pre-login information.
     - A [UserDB][dovecot::docs::userdb] lookup retrieves post-login information specific to a user.
+
+[docs::sieve::subaddressing]: ../advanced/mail-sieve.md#subaddress-mailbox-routing
+[web::subaddress-use-cases]: https://www.codetwo.com/admins-blog/plus-addressing/
+[wikipedia::subaddressing]: https://en.wikipedia.org/wiki/Email_address#Sub-addressing
+[ms-exchange-docs::limitations]: https://learn.microsoft.com/en-us/exchange/recipients-in-exchange-online/plus-addressing-in-exchange-online#using-plus-addresses
+
+[postfix-docs::virtual-alias]: http://www.postfix.org/VIRTUAL_README.html#virtual_alias
+[postfix-docs::recipient-delimiter]: http://www.postfix.org/postconf.5.html#recipient_delimiter
+[dovecot-docs::config::recipient-delimiter]: https://doc.dovecot.org/settings/core/#core_setting-recipient_delimiter

docs/content/config/advanced/mail-sieve.md

@@ -81,22 +81,76 @@ For more examples or a detailed description of the Sieve language have a look at
 [sieve-info::examples]: http://sieve.info/examplescripts
 [third-party::sieve-examples]: https://support.tigertech.net/sieve#sieve-example-rules-jmp
 
-## Automatic Sorting Based on Subaddresses
+## Automatic Sorting Based on Subaddresses { #subaddress-mailbox-routing }
 
-It is possible to sort subaddresses such as `user+mailing-lists@example.com` into a corresponding folder (here: `INBOX/Mailing-lists`) automatically.
+When mail is delivered to your account, it is possible to organize storing mail into folders by the [subaddress (tag)][docs::accounts-subaddressing] used.
 
-```sieve
+!!! example "Example: `user+<tag>@example.com` to `INBOX/<Tag>`"
-require ["envelope", "fileinto", "mailbox", "subaddress", "variables"];
 
-if envelope :detail :matches "to" "*" {
+    This example sorts mail into inbox folders by their tag:
+
+    ```sieve
+    require ["envelope", "fileinto", "mailbox", "subaddress", "variables"];
+
+    # Check if the mail recipient address has a tag (:detail)
+    if envelope :detail :matches "to" "*" {
+      # Create a variable `tag`, with the the captured `to` value normalized (SoCIAL => Social)
       set :lower :upperfirst "tag" "${1}";
-  if mailboxexists "INBOX.${1}" {
+
-    fileinto "INBOX.${1}";
+      # Store the mail into a folder with the tag name, nested under your inbox folder:
+      if mailboxexists "INBOX.${tag}" {
+        fileinto "INBOX.${tag}";
       } else {
         fileinto :create "INBOX.${tag}";
       }
-}
+    }
-```
+    ```
+
+    When receiving mail for `user+social@example.com` it would be delivered into the `INBOX/Social` folder.
+
+??? tip "Only redirect mail for specific tags"
+
+    If you want to handle only specific tags this way, you could adjust these two lines from the prior example:
+
+    ```sieve
+    # Instead of `:matches`, use the default comparator `:is` (exact match)
+    if envelope :detail "to" "social" {
+      set "tag" "Social";
+    ```
+
+    ```sieve
+    # You can provide a list of values to match for:
+    if envelope :detail "to" ["azure", "aws"] {
+      set "tag" "Cloud";
+    ```
+
+    ```sieve
+    # Similar to `:matches`, but `:regex` is more full featured for pattern matching.
+    # NOTE: This example needs you to `require` the "regex" extension
+    if envelope :detail :regex "to" "^cloud-(azure|aws)$" {
+      # Normalize the captured azure/aws tag as the resolved value is no longer fixed:
+      set :lower :upperfirst "vendor" "${1}";
+      # If a `.` exists in the tag, it will create nested folders:
+      set "tag" "Cloud.${vendor}";
+    ```
+
+    **NOTE:** There is no need to lowercase the tag in the conditional as the [`to` value is a case-insensitive check][sieve-docs::envelope].
+
+??? abstract "Technical Details"
+
+     - Dovecot supports this feature via the _Sieve subaddress extension_ ([RFC 5233][rfc::5233::sieve-subaddress]).
+     - Only a single tag per subaddress is supported. Any additional tag delimiters are part of the tag value itself.
+     - The Dovecot setting [`recipient_delimiter`][dovecot-docs::config::recipient_delimiter] (default: `+`) configures the tag delimiter. This is where the `local-part` of the recipient address will split at, providing the `:detail` (tag) value for Sieve.
+
+    ---
+
+    `INBOX` is the [default namespace configured by Dovecot][dovecot-docs::namespace].
+
+    - If you omit the `INBOX.` prefix from the sieve script above, the mailbox (folder) for that tag is created at the top-level alongside your Trash and Junk folders.
+    - The `.` between `INBOX` and `${tag}` is important as a [separator to distinguish mailbox names][dovecot-docs::mailbox-names]. This can vary by mailbox format or configuration. DMS uses [`Maildir`][dovecot-docs::mailbox-formats::maildir] by default, which uses `.` as the separator.
+    - [`lmtp_save_to_detail_mailbox = yes`][dovecot-docs::config::lmtp_save_to_detail_mailbox] can be set in `/etc/dovecot/conf.d/20-lmtp.conf`:
+        - This implements the feature globally, except for the tag normalization and `INBOX.` prefix parts of the example script.
+        - However, if the sieve script is also present, the script has precedence and will handle this task instead when the condition is successful, otherwise falling back to the global feature.
 
 ## Manage Sieve
 
@@ -122,3 +176,14 @@ The extension is known to work with the following ManageSieve clients:
 
 - **[Sieve Editor](https://github.com/thsmi/sieve)**  a portable standalone application based on the former Thunderbird plugin.
 - **[Kmail](https://kontact.kde.org/components/kmail/)**  the mail client of [KDE](https://kde.org/)'s Kontact Suite.
+
+[docs::accounts-subaddressing]: ../account-management/overview.md#subaddressing
+
+[dovecot-docs::namespace]: https://doc.dovecot.org/configuration_manual/namespace/
+[dovecot-docs::mailbox-names]: https://doc.dovecot.org/configuration_manual/sieve/usage/#mailbox-names
+[dovecot-docs::mailbox-formats::maildir]: https://doc.dovecot.org/admin_manual/mailbox_formats/maildir/#maildir-mbox-format
+[dovecot-docs::config::lmtp_save_to_detail_mailbox]: https://doc.dovecot.org/settings/core/#core_setting-lmtp_save_to_detail_mailbox
+[dovecot-docs::config::recipient_delimiter]: https://doc.dovecot.org/settings/core/#core_setting-recipient_delimiter
+
+[rfc::5233::sieve-subaddress]: https://datatracker.ietf.org/doc/html/rfc5233
+[sieve-docs::envelope]: https://thsmi.github.io/sieve-reference/en/test/core/envelope.html