Namespaces

Dovecot supports fully configurable, hierarchical namespaces, which can use different storage drivers.

Their original and primary purpose is to provide Namespace IMAP extension (RFC 2342) support, which allows giving IMAP clients hints about where to locate mailboxes and whether they're private, shared or public.

Dovecot namespaces can be used for several other purposes too:

Changing the hierarchy separator
Providing backwards compatibility when switching from another IMAP server
Provides support for public shared mailboxes and user shared mailboxes mailboxes
Allows having mails in multiple different locations with possibly different formats

These different locations and drivers are presented to the client as a single tree.

Each namespace has:

prefix (usually empty or "INBOX.")
namespace separator (usually '/' or '.')
0 or more folders

There must be one namespace where the case-insensitive folder named INBOX exists.

All visible namespaces must have the same separator.

Inside each namespace there is a list of folders, which form a sub-hierarchy.

Folder Names

Each folder has a name. In configuration files and log files Dovecot almost always uses the "virtual name", which uses the configured namespace's hierarchy separator as well as the namespace prefix. Depending on the used LAYOUT in mail_location the internal folder name may be different. The internal name is stored in databases (e.g. mailbox subscriptions), which allows changing the namespace prefix or separator without having to change the databases.

The folder names use UTF-8 character set internally. All folder names must be valid UTF-8. With LAYOUT=fs and LAYOUT=Maildir++ the folder names are stored in filesystem paths as mUTF-7 (see IMAP RFC 3501) mainly for legacy reasons. This can be changed by specifying the UTF8 parameter in mail_location.

Folder Name Lengths

Folder name length restrictions:

Maximum length of an individual folder name within a hierarchy is 255 bytes. For example with "a/b/c" hierarchy each of the a, b and c can be a maximum of 255 bytes.
The maximum folder path length is 4096 bytes.

The maximum folder name lengths work correctly when folder names aren't stored in filesystem, i.e. LAYOUT=index is used. Otherwise the OS adds its own limitations to path name lengths and the full 4096 bytes can't be used. With LAYOUT=Maildir++ the path must fit to 254 bytes (due to OS limitations).

Parent Folders

A folder can have one or more parent folders that do not physically exist. These are presented with \NoSelect or \Nonexistent attribute. It's possible to try to avoid creating these by using the NO-NOSELECT option in mail_location.

Configuration

If the Dovecot configuration doesn't explicitly specify a namespace, the inbox namespace is created automatically.

Namespace configuration is defined within a dovecot configuration block with the format:

namespace <section-name> {
  [... namespace settings ...]
}

The optional section name is only used internally within configuration. It allows you to update an existing namespace - by repeating the namespace block and adding additional configuration settings - or allows userdb to override namespace settings for specific users, e.g.:

namespace/section-name/prefix=foo/

Example configuration for default namespace:

namespace inbox {
  separator = .
  prefix =
  inbox = yes
}

Settings

`namespace`

Default	[None]
Value	string

Name of the namespace.

Giving name is optional, but doing so enables referencing the configuration later on.

Example, to name a namespace foo:

namespace foo {
  [...]
}

`namespace/alias_for`

Default	[None]
Value	string

Defines the namespace prefix for purposes of alias detection.

If multiple namespaces point to the same location, they should be marked as aliases against one primary namespace. This avoids duplicating work for some commands (listing the same mailbox multiple times).

Mail user variables can be used.

Note: Alias namespaces often have hidden=yes and list=no so they are not visible unless clients have specifically configured them, and they're typically used when migrating to a different namespace prefix for existing users.

Example:

namespace {
  # If primary namespace has empty prefix
  alias_for =

  # OR if primary namespace has 'prefix=INBOX/'
  alias_for=INBOX/
}

`namespace/disabled`

Default	`no`
Value	boolean

If yes, namespace is disabled and cannot be accessed by user in any way.

Useful when returned by a userdb lookup to easily configure per-user namespaces.

`namespace/hidden`

Default	`no`
Value	boolean

If yes, namespace will be hidden from IMAP NAMESPACE (RFC 2342) command.

`namespace/ignore_on_failure`

Default	`no`
Value	boolean

If namespace namespace/location fails to load, by default the entire session will fail to start. If this is set, this namespace will be ignored instead.

`namespace/inbox`

Default	`no`
Value	boolean

If yes, this namespace will be considered the one holding the INBOX folder.

There can be only one namespace defined like this.

`namespace/list`

Default	`yes`
Value	string
Allowed Values	`yesnochildren`
See Also	`namespace/hidden`

Include this namespace in LIST output when listing its parent's folders.

Options:

Value	Description
`children`	Namespace prefix list listed only if it has child mailboxes.
`no`	Namespace and mailboxes not listed unless listing requests explicitly mailboxes under the namespace prefix.
`yes`	Namespace and mailboxes are always listed.

It is still possible to list the namespace's folders by explicitly asking for them. For example, if this setting is no, using LIST "" * with namespace prefix "lazy-expunge/" won't list it, but using LIST "" lazy-expunge/* lists all folders under it.

`namespace/location`

Default	`mail_location`
Value	string

Specifies driver and parameters for physical mailbox storage. It allows an override of the mail_location setting for a namespace.

Mail user variables can be used.

Example:

namespace {
  location = sdbox:/archive/%u
}

`namespace/order`

Default	[None]
Value	unsigned integer

Sets display order in IMAP NAMESPACE (RFC 2342) command.

Namespaces are automatically numbered if this setting does not exist.

`namespace/prefix`

Default	[None]
Value	string

Specifies prefix for namespace.

Note: Must end with namespace/separator.

Mail user variables can be used.

Example:

namespace {
  prefix = Shared/
  separator = /
}

`namespace/separator`

Default	`"." for Maildir; "/" for other mbox formats`
Value	string
See Also	namespace hierarchy separators

Specifies the hierarchy separator for the namespace.

The separator is a single character, which can't then otherwise be used in folder names.

The commonly used separators are . and /, but other separators can be used as well. For example ^ is less likely to be found in normal folder names.

Recommended value is to leave it empty and accept the default value.

`namespace/subscriptions`

Default	`yes`
Value	boolean

Whether subscriptions are stored in this namespace.

This is usually no for shared namespaces so that the shared folders' subscriptions are stored in the user's primary subscriptions file. If no, the subscriptions are stored in the first parent namespace (based on the prefix) that has this setting enabled.

Example: If this setting is no for a namespace with prefix=foo/bar/, Dovecot first sees if there's a prefix=foo/ namespace with subscriptions=yes and then a namespace with an empty prefix. If neither is found, an error is given.

`namespace/type`

Default	`private`
Value	string
Allowed Values	`privatesharedpublic`

The namespace type. One of:

Type	Description
`public`	Contains public shared mailboxes.
`private`	Typically contains only user's own private mailboxes.
`shared`	Contains other users' user shared mailboxes.

Hierarchy Separators

namespace/separator specifies the character that is used to separate the parent mailbox from its child mailbox.

For example if you have a mailbox "foo" with child mailbox "bar", the full path to the child mailbox would be "foo/bar" with / as the separator, and "foo.bar" with . as the separator.

IMAP clients, Sieve scripts, and many parts of Dovecot configuration use the configured separator when referring to mailboxes. This means that if you change the separator, you may break things.

However, changing the separator doesn't change the on-disk "layout separator".

Example:

Note

The "namespace separator" changes only the "mailbox name", but doesn't change the directory where the mails are stored. The "layout separator" can only be changed by changing LAYOUT, which also affects the entire directory structure.

The layout separator also restricts the mailbox names. For example if the layout separator is ., you can't just set separator to / and create a mailbox named foo.bar. If you need to do this, you can use listescape plugin to escape the mailbox names.

A commonly used separator is /. It probably causes the least amount of trouble with different IMAP clients. The ^ separator is troublesome with Thunderbird. If \ has to be used, it needs to be escaped in configuration:

namespace {
  separator = "\\"
}

You should use the same hierarchy separator for all namespaces. All list=yes namespaces must use the same separator, but if you find it necessary (e.g. for backwards compatibility namespaces) you may use different separators for list=no namespaces.

Values From userdb

To change namespace settings from userdb, you need to return namespace/<name>/setting=value.

To create a namespace, make sure you first return namespace=<name>[,<name>,...] and settings after this.

Note that the namespace setting must list all the namespaces that are used - there's currently no way to simply add a namespace.

userdb {
  driver = static
  args = namespace=inbox,special namespace/special/location=sdbox:/var/special/%u namespace/special/prefix=special/
}

Shared Mailboxes

See shared mailboxes.

Examples

Mixed mbox and Maildir

If you have your INBOX as mbox in /var/mail/username and the rest of the mailboxes in Maildir format under ~/Maildir, you can do this by creating two namespaces:

namespace {
  separator = /
  prefix = "#mbox/"
  location = mbox:~/mail:INBOX=/var/mail/%u
  inbox = yes
  hidden = yes
  list = no
}

namespace {
  separator = /
  prefix =
  location = maildir:~/Maildir
}

Without the list = no setting in the first namespace, clients would see the "#mbox" namespace as a non-selectable mailbox named "#mbox" but with child mailboxes (the mbox files in the "~/mail" directory), i.e. like a directory. So specifically with inbox = yes, having list = no is often desirable.

Backwards Compatibility: UW-IMAP

When switching from UW-IMAP and you don't want to give users full access to filesystem, you can create hidden namespaces which allow users to access their mails using their existing namespace settings in clients.

# default namespace
namespace inbox {
  separator = /
  prefix =
  inbox = yes
}

# for backwards compatibility:
namespace compat1 {
  separator = /
  prefix = mail/
  hidden = yes
  list = no
  alias_for =
}
namespace compat2 {
  separator = /
  prefix = ~/mail/
  hidden = yes
  list = no
  alias_for =
}
namespace compat3 {
 separator = /
 prefix = ~%u/mail/
 hidden = yes
 list = no
 alias_for =
}

Backwards Compatibility: Courier IMAP

Recommended: You can continue using the same INBOX. namespace as Courier:

namespace inbox {
  separator = .
  prefix = INBOX.
  inbox = yes
}

Alternatively: Create the INBOX. as a compatibility name, so old clients can continue using it while new clients will use the empty prefix namespace:

namespace inbox {
  separator = /
  prefix =
  inbox = yes
}

namespace compat {
  separator = .
  prefix = INBOX.
  inbox = no
  hidden = yes
  list = no
  alias_for =
}

The separator=/ allows the INBOX to have child mailboxes. Otherwise with separator=. it wouldn't be possible to know if "INBOX.foo" means INBOX's "foo" child or the root "foo" mailbox in "INBOX." compatibility namespace. With separator=/ the difference is clear with "INBOX/foo" vs. "INBOX.foo".

The alternative configuration is not recommended, as it may introduce issues:

Although clients may do LIST INBOX.*, they may still do LSUB *, resulting in mixed results.
If clients used empty namespace with Courier, they now see the mailboxes with different names, resulting in redownloading of all mails (except INBOX).
Some clients may have random errors auto-detecting the proper default folders (Sent, Drafts etc) if the client settings refer to old paths while the server lists new paths.

Per-user Namespace Location From SQL

You need to give the namespace a name, for example "docs" below:

namespace docs {
  type = public
  separator = /
  prefix = Public/
}

Then you have an SQL table like:

sql

CREATE TABLE Namespaces (
  [...]
  Location varchar(255) NOT NULL,
  [...]
)

Now if you want to set the namespace location from the Namespaces table, use something like:

user_query = SELECT Location as 'namespace/docs/location' FROM Namespaces WHERE ..

If you follow some advice to separate your "INBOX", "shared/" and "public/" namespaces by choosing "INBOX/" as your prefix for the inboxes you will see, that you run into troubles with subscriptions. Thats, because there is no parent namespace for "shared/" and "public/" if you set subscriptions = no for those namespaces.

If you set subscriptions = yes for "shared/" and "public/" you will see yourself in the situation, that all users share the same subscription files under the location of those mailboxes.

One good solution is, to create a so called "hidden subscription namespace" with subscriptions turned on and setting subscriptions = no for the other namespaces:

namespace subscriptions {
  subscriptions = yes
  prefix = ""
  list = no
  hidden = yes
}

namespace inbox {
  inbox = yes
  location =
  subscriptions = no

  prefix = INBOX/
  separator = /

  mailbox Drafts {
    auto = subscribe
    special_use = \Drafts
  }

  mailbox Sent {
    auto = subscribe
    special_use = \Sent
  }

  mailbox "Sent Messages" {
    special_use = \Sent
  }

  mailbox Spam {
    auto = subscribe
    special_use = \Junk
  }

  mailbox Trash {
    auto = subscribe
    special_use = \Trash
  }
}

namespace {
  type = shared
  prefix = shared/%%u/
  location = mdbox:%%h/mdbox:INDEXPVT=%h/mdbox/shared
  list = children
  subscriptions = no
}

namespace {
  type = public
  separator = /
  prefix = public/
  location = mdbox:/usr/local/mail/public/mdbox:INDEXPVT=%h
  subscriptions = no
  list = children
}

Mailbox Settings

Mailbox configuration is defined within a dovecot configuration block, inside of a namespace block, with the format:

mailbox <mailbox-name> {
  [... mailbox settings ...]
}

The mailbox-name specifies the full mailbox name; if it has spaces, you can put it into quotes:

mailbox "Test Mailbox" {
   [...]
}

Settings

`namespace/mailbox/auto`

Default	`no`
Value	string
Allowed Values	`createnosubscribe`

Autocreate and/or subscribe to the mailbox?

Value	Description
`create`	Autocreate but don't autosubscribe
`no`	Don't autocreate or autosubscribe
`subscribe`	Autocreate and autosubscribe

Autocreated mailboxes are created lazily to disk only when accessed for the first time. The autosubscribed mailboxes aren't written to subscriptions file, unless SUBSCRIBE command is explicitly used for them.

`namespace/mailbox/autoexpunge`

Default	`no`
Value	time
See Also	`namespace/mailbox/autoexpunge_max_mails`

Expunge all mails in this mailbox whose saved-timestamp is older than this value.

For IMAP and POP3 this happens after the client is already disconnected.

For LMTP this happens when the user's mail delivery is finished. Note that in case there are multiple recipients, autoexpunging is done only for some of the recipients to prevent delays with the mail delivery: The last recipient user is autoexpunged first. Next, the first recipient user is autoexpunged (because the first user's mail was kept open in case it could be directly copied to the other users). None of the middle recipient users are autoexpunged.

mailbox_list_index = yes is highly recommended when using this setting, as it avoids actually opening the mailbox to see if anything needs to be expunged.

mail_always_cache_fields = date.save is also recommended when using this setting with sdbox or Maildir, as it avoids using stat() to find out the mail's saved-timestamp. With mdbox format this isn't necessary, since the saved-timestamp is always available.

`namespace/mailbox/autoexpunge_max_mails`

Default	[None]
Value	unsigned integer

Mails are autoexpunged until mail count is at or below this number of messages.

Once this threshold has been reached, namespace/mailbox/autoexpunge processing is done.

`namespace/mailbox/special_use`

Default	[None]
Value	string
Changes	Changed: 2.4.0 Using non-standard special-use flags will result in a warning message at startup.

Space-separated list of SPECIAL-USE (RFC 6154) flags to broadcast for the mailbox.

There are no validity checks, so you could specify anything you want here, but it's not a good idea to use other than the standard ones specified in the RFC.

Example

namespace inbox {
  # the namespace prefix isn't added again to the mailbox names.
  #prefix = INBOX.
  inbox = yes
  # ...

  mailbox Trash {
    auto = no
    special_use = \Trash
  }

  mailbox Drafts {
    auto = no
    special_use = \Drafts
  }

  mailbox Sent {
    auto = subscribe # autocreate and autosubscribe the Sent mailbox
    special_use = \Sent
  }

  mailbox "Sent Messages" {
    auto = no
    special_use = \Sent
  }

  mailbox Spam {
    auto = create # autocreate Spam, but don't autosubscribe
    special_use = \Junk
  }

  mailbox virtual/All { # if you have a virtual "All messages" mailbox
    auto = no
    special_use = \All
  }
}

Databases

Mechanisms

Formats

Extensions

Namespaces ​

Folder Names ​

Folder Name Lengths ​

Parent Folders ​

Configuration ​

Settings ​

namespace

namespace/alias_for

namespace/disabled

namespace/hidden

namespace/ignore_on_failure

namespace/inbox

namespace/list

namespace/location

namespace/order

namespace/prefix

namespace/separator

namespace/subscriptions

namespace/type

Hierarchy Separators ​

Values From userdb ​

Shared Mailboxes ​

Examples ​

Mixed mbox and Maildir ​

Backwards Compatibility: UW-IMAP ​

Backwards Compatibility: Courier IMAP ​

Per-user Namespace Location From SQL ​

Mailbox Settings ​

Settings ​

namespace/mailbox/auto

namespace/mailbox/autoexpunge

namespace/mailbox/autoexpunge_max_mails

namespace/mailbox/special_use

Example ​

Namespaces

Folder Names

Folder Name Lengths

Parent Folders

Configuration

Settings

`namespace`

`namespace/alias_for`

`namespace/disabled`

`namespace/hidden`

`namespace/ignore_on_failure`

`namespace/inbox`

`namespace/list`

`namespace/location`

`namespace/order`

`namespace/prefix`

`namespace/separator`

`namespace/subscriptions`

`namespace/type`

Hierarchy Separators

Values From userdb

Shared Mailboxes

Examples

Mixed mbox and Maildir

Backwards Compatibility: UW-IMAP

Backwards Compatibility: Courier IMAP

Per-user Namespace Location From SQL

Mailbox Settings

Settings

`namespace/mailbox/auto`

`namespace/mailbox/autoexpunge`

`namespace/mailbox/autoexpunge_max_mails`

`namespace/mailbox/special_use`

Example