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>
This commit is contained in:
hnws
GitHub
parent
de05ce91a2
commit
630e083c9a
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
#}
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in New Issue