From 630e083c9aa5e8184c36f3f165dec4b88de3e6ef Mon Sep 17 00:00:00 2001 From: hnws Date: Tue, 22 Jun 2021 18:28:43 -0400 Subject: [PATCH] docs: Add example for customizing IMAP folders (#2045) * docs: Add example for customizing IMAP folders (mailboxes) * chore: Update `15-mailboxes.conf` to sync with upstream This config has not been updated since 2016 (ignoring the Junk autosubscribe addition). Synced to upstream equivalent at https://github.com/dovecot/core/blob/master/doc/example-config/conf.d/15-mailboxes.conf Retains the `Archive` example definition from this PR and prior `auto = subscribe` additions. --- Co-authored-by: Brennan Kinney <5098581+polarathene@users.noreply.github.com> --- README.md | 6 ++ .../examples/uses-cases/imap-folders.md | 73 +++++++++++++++++++ docs/mkdocs.yml | 1 + target/dovecot/15-mailboxes.conf | 73 +++++++++++++++---- 4 files changed, 139 insertions(+), 14 deletions(-) create mode 100644 docs/content/examples/uses-cases/imap-folders.md diff --git a/README.md b/README.md index 3d1bfda6..ebf81e91 100644 --- a/README.md +++ b/README.md @@ -176,6 +176,12 @@ If you got any problems with SPF and/or forwarding mails, give [SRS](https://git See the [documentation](https://docker-mailserver.github.io/docker-mailserver/edge/config/security/understanding-the-ports/) for further details and best practice advice, **especially regarding security concerns**. +#### Mailboxes (_aka IMAP Folders_) + +`INBOX` is setup by default with the special IMAP folders `Drafts`, `Sent`, `Junk` and `Trash`. You can learn how to modify or add your own folders (_including additional special folders like `Archive`_) by visiting our docs page [_Customizing IMAP Folders_][docs-examples-imapfolders] for more information. + +[docs-examples-imapfolders]: https://docker-mailserver.github.io/docker-mailserver/edge/examples/use-cases/imap-folders + ## Examples ### With Relevant Environmental Variables diff --git a/docs/content/examples/uses-cases/imap-folders.md b/docs/content/examples/uses-cases/imap-folders.md new file mode 100644 index 00000000..ae6b7559 --- /dev/null +++ b/docs/content/examples/uses-cases/imap-folders.md @@ -0,0 +1,73 @@ +--- +title: 'Use Cases | Customize Mailbox Folders' +hide: + - toc # Hide Table of Contents for this page +--- + +# Mailboxes (_aka IMAP Folders_) + +`INBOX` is setup as the private [`inbox` namespace][dovecot-docs-namespaces]. By default [`target/dovecot/15-mailboxes.conf`][gh-config-dovecot-mailboxes] configures the special IMAP folders `Drafts`, `Sent`, `Junk` and `Trash` to be automatically created and subscribed. They are all assigned to the private [`inbox` namespace][dovecot-docs-namespaces] (_which implicitly provides the `INBOX` folder_). + +These IMAP folders are considered special because they add a [_"SPECIAL-USE"_ attribute][rfc-6154], which is a standardized way to communicate to mail clients that the folder serves a purpose like storing spam/junk mail (`\Junk`) or deleted mail (`\Trash`). This differentiates them from regular mail folders that you may use for organizing. + +## Adding a mailbox folder + +See [`target/dovecot/15-mailboxes.conf`][gh-config-dovecot-mailboxes] for existing mailbox folders which you can modify or uncomment to enable some other common mailboxes. For more information try the [official Dovecot documentation][dovecot-docs-mailboxes]. + +The `Archive` special IMAP folder may be useful to enable. To do so, make a copy of [`target/dovecot/15-mailboxes.conf`][gh-config-dovecot-mailboxes] and uncomment the `Archive` mailbox definition. Mail clients should understand that this folder is intended for archiving mail due to the [`\Archive` _"SPECIAL-USE"_ attribute][rfc-6154]. + +With the provided [docker-compose.yml][gh-config-dockercompose] example, a volume bind mounts the host directory `config` to the container location `/tmp/docker-mailserver`. Config file overrides should instead be mounted to a different location as described in [Overriding Configuration for Dovecot][docs-config-overrides-dovecot]: + +```YAML +volumes: + ... + - ./config/dovecot/15-mailboxes.conf:/etc/dovecot/conf.d/15-mailboxes.conf:ro +``` + +## Caution + +### Adding folders to an existing setup + +Handling of newly added mailbox folders can be inconsistent across mail clients: + +- Users may experience issues such as archived emails only being available locally. +- Users may need to migrate emails manually between two folders. + +### Support for `SPECIAL-USE` attributes + +Not all mail clients support the `SPECIAL-USE` attribute for mailboxes (_defined in [RFC 6154][rfc-6154]_). These clients will treat the mailbox folder as any other, using the name assigned to it instead. + +Some clients may still know to treat these folders for their intended purpose if the mailbox name matches the common names that the `SPECIAL-USE` attributes represent (_eg `Sent` as the mailbox name for `\Sent`_). + +### Internationalization (i18n) + +Usually the mail client will know via context such as the `SPECIAL-USE` attribute or common English mailbox names, to provide a localized label for the users preferred language. + +Take care to test localized names work well as well. + +### Email Clients Support + +- If a new mail account is added without the `SPECIAL-USE` attribute enabled for archives: + - **Thunderbird** suggests and may create an `Archives` folder on the server. + - **Outlook for Android** archives to a local folder. + - **Spark for Android** archives to server folder named `Archive`. +- If a new mail account is added after the `SPECIAL-USE` attribute is enabled for archives: + - **Thunderbird**, **Outlook for Android** and **Spark for Android** will use the mailbox folder name assigned. + +!!! caution "Windows Mail" + + **Windows Mail** has been said to ignore `SPECIAL-USE` attribute and look only at the mailbox folder name assigned. + +!!! note "Needs citation" + + This information is provided by the community. + + It presently lacks references to confirm the behaviour. If any information is incorrect please let us know! :smile: + + +[docs-config-overrides-dovecot]: ../../config/advanced/override-defaults/dovecot.md#override-configuration +[gh-config-dockercompose]: https://github.com/docker-mailserver/docker-mailserver/blob/master/docker-compose.yml +[gh-config-dovecot-mailboxes]: https://github.com/docker-mailserver/docker-mailserver/blob/master/target/dovecot/15-mailboxes.conf +[dovecot-docs-namespaces]: https://doc.dovecot.org/configuration_manual/namespace/#namespace-inbox +[dovecot-docs-mailboxes]: https://doc.dovecot.org/configuration_manual/namespace/#mailbox-settings +[rfc-6154]: https://datatracker.ietf.org/doc/html/rfc6154 diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index e21aa799..0f3c7556 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -147,6 +147,7 @@ nav: - 'Mailserver behind Proxy': examples/tutorials/mailserver-behind-proxy.md - 'Use Cases': - 'Forward-Only Mailserver with LDAP': examples/uses-cases/forward-only-mailserver-with-ldap-authentication.md + - 'Customize IMAP Folders': examples/uses-cases/imap-folders.md - 'FAQ' : faq.md - 'Contributing': - 'Issues and Pull Requests': contributing/issues-and-pull-requests.md diff --git a/target/dovecot/15-mailboxes.conf b/target/dovecot/15-mailboxes.conf index 131d11a1..329ae7ee 100644 --- a/target/dovecot/15-mailboxes.conf +++ b/target/dovecot/15-mailboxes.conf @@ -2,19 +2,50 @@ ## Mailbox definitions ## +# Each mailbox is specified in a separate mailbox section. The section name +# specifies the mailbox name. If it has spaces, you can put the name +# "in quotes". These sections can contain the following mailbox settings: +# +# auto: +# Indicates whether the mailbox with this name is automatically created +# implicitly when it is first accessed. The user can also be automatically +# subscribed to the mailbox after creation. The following values are +# defined for this setting: +# +# no - Never created automatically. +# create - Automatically created, but no automatic subscription. +# subscribe - Automatically created and subscribed. +# +# special_use: +# A space-separated list of SPECIAL-USE flags (RFC 6154) to use for the +# mailbox. There are no validity checks, so you could specify anything +# you want in here, but it's not a good idea to use flags other than the +# standard ones specified in the RFC: +# +# \All - This (virtual) mailbox presents all messages in the +# user's message store. +# \Archive - This mailbox is used to archive messages. +# \Drafts - This mailbox is used to hold draft messages. +# \Flagged - This (virtual) mailbox presents all messages in the +# user's message store marked with the IMAP \Flagged flag. +# \Important - This (virtual) mailbox presents all messages in the +# user's message store deemed important to user. +# \Junk - This mailbox is where messages deemed to be junk mail +# are held. +# \Sent - This mailbox is used to hold copies of messages that +# have been sent. +# \Trash - This mailbox is used to hold messages that have been +# deleted. +# +# comment: +# Defines a default comment or note associated with the mailbox. This +# value is accessible through the IMAP METADATA mailbox entries +# "/shared/comment" and "/private/comment". Users with sufficient +# privileges can override the default value for entries with a custom +# value. + # NOTE: Assumes "namespace inbox" has been defined in 10-mail.conf. namespace inbox { - - #mailbox name { - # auto=create will automatically create this mailbox. - # auto=subscribe will both create and subscribe to the mailbox. - #auto = no - - # Space separated list of IMAP SPECIAL-USE attributes as specified by - # RFC 6154: \All \Archive \Drafts \Flagged \Junk \Sent \Trash - #special_use = - #} - # These mailboxes are widely used and could perhaps be created automatically: mailbox Drafts { auto = subscribe @@ -35,17 +66,31 @@ namespace inbox { auto = subscribe special_use = \Sent } -# mailbox "Sent Messages" { -# special_use = \Sent -# } + + #mailbox "Sent Messages" { + # special_use = \Sent + #} + + #mailbox Archive { + # auto = subscribe + # special_use = \Archive + #} # If you have a virtual "All messages" mailbox: #mailbox virtual/All { # special_use = \All + # comment = All my messages #} # If you have a virtual "Flagged" mailbox: #mailbox virtual/Flagged { # special_use = \Flagged + # comment = All my flagged messages + #} + + # If you have a virtual "Important" mailbox: + #mailbox virtual/Important { + # special_use = \Important + # comment = All my important messages #} }