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.
This commit is contained in:
polarathene
parent
28ca7d3141
commit
3ad4a359e3
|
|
@ -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
|
||||
recipient_delimiter = -
|
||||
```
|
||||
A common use-case is to use a unique tag for each service you register your email address with.
|
||||
|
||||
- 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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
require ["envelope", "fileinto", "mailbox", "subaddress", "variables"];
|
||||
!!! example "Example: `user+<tag>@example.com` to `INBOX/<Tag>`"
|
||||
|
||||
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
|
||||
|
|
|
|||
Loading…
Reference in New Issue