Mail Location Setting

Settings

mail_alt_check

Default	yes
Value	boolean
See Also	mail_alt_path

Whether to perform a sanity check and warn if mail_alt_path changes from the last access. This can catch accidentally broken configurations before users start reporting missing mails. The downside to this check is some additional disk IO.

mail_alt_path

Default	[None]
Value	string
See Also	dbox alternate storage

Specifies the dbox alternate storage path.

mail_cache_path

Default	<same as mail_index_path setting>
Value	string

Place dovecot.index.cache files to this directory instead of among the other index files. This may be used as an optimization to split most index files to the fastest (smallest) storage while keeping cache files in a slightly slower (larger) storage.

mail_control_path

Default	[None]
Value	string

Location for (mailbox-format specific) control files.

mail_driver

Default	[None]
Value	string
See Also	Mailbox Formats Mailbox Root Autodetection mail_path

One of the mailbox formats described at Mailbox Formats.

For an empty value or auto, Dovecot attempts to find the mailboxes automatically.

mail_inbox_path

Default	[None]
Value	string
See Also	mail_path

Path to the INBOX mailbox. The path doesn't have to be absolute - it is relative to the mail_path.

This is often used with mbox format where INBOX is in /var/mail/ while the rest of the folders are under the user's home directory.

This can also be used to specify a different INBOX path with Maildir:

 mail_driver = maildir
 mail_path = ~/Maildir
 mail_inbox_path = ~/Maildir/.INBOX

mail_index_path

Default	<same as mail_path setting>
Value	string
See Also	Mail Location: Index Files

Location of index files.

mail_index_private_path

Default	[None]
Value	string
See Also	public shared mailboxes

The private index files are used with shared mailboxes to provide private (per-user) message flags.

mail_path

Default	<specific to mail_driver setting>
Value	string
See Also	Mail User Variables Home Directories for Virtual Users mail_driver

Path to a directory where the mail is stored. Mail User Variables are commonly used here.

Usually the mails should be stored in a sub-directory under the home directory, but not the home directory itself (see Home Directories for Virtual Users).

The path must be absolute, not a relative path. Even if relative paths appear to work, this usage is deprecated and will likely stop working at some point.

mail_volatile_path

Default	[None]
Value	string

Specifies the location of volatile files. This includes lock files and potentially other files that don't need to exist permanently, so it can point to an in-memory filesystem (tmpfs). This is especially useful to avoid creating lock files to NFS or other remote filesystems.

mailbox_directory_name

Default	<specific to mail_driver setting>
Value	string
See Also	mail_driver mailbox_directory_name_legacy

Specifies the directory name used for mailbox, index, and control directory paths. See the individual mailbox format pages for further information. For example dbox-Mails with dbox.

With mbox format this works differently. The user-provided mailbox name is the directory name, while mailbox_directory_name is the mbox file. For example with mailbox_directory_name=mbox, creating foo/bar mailbox name ends up creating .../foo/bar/mbox file.

mailbox_directory_name_legacy

Default	no
Value	boolean
See Also	mailbox_directory_name

If no, mailbox_directory_name applies also to index and control directories. The only reason to set this to yes is if you already have an existing Dovecot installation with the legacy DIRNAME (rather than FULLDIRNAME) parameter and don't want to migrate the data.

mailbox_list_drop_noselect

Default	yes
Value	boolean

Specifies whether to automatically delete NoSelect mailboxes that have no children. These mailboxes are sometimes confusing to users. Also if a NoSelect mailbox is attempted to be created with CREATE box/, it's created as selectable mailbox instead.

INFO

Maildir layout does not support NoSelect mailboxes, so this setting has no effect with it.

mailbox_list_index_prefix

Default	dovecot.list.index
Value	string

Prefix for the mailbox list index filename. It may also optionally include a path (relative to mail_index_path) to place it in a different directory.

mailbox_list_iter_from_index_dir

Default	no
Value	boolean

Perform mailbox listing using the mail_index_path directories instead of the mail_path directories. Mainly useful when the index file storage is on a faster storage.

mailbox_list_layout

Default	fs
Value	string
Allowed Values	fsindexMaildir++
See Also	dbox Maildir mbox

Directory layout to use.

Value	Description
Maildir++	The default used by Maildir.
fs	The default used by mbox and dbox.
index	Uses mailbox GUIDs as the directory names. The mapping between mailbox names and GUIDs exists in dovecot.list.index* files.

INFO

The mail_driver setting provides the default value, that the mailbox_list_layout setting can override.

mailbox_list_storage_escape_char

Default	[None] The default for imapc storage is %.
Value	string
See Also	mailbox_list_visible_escape_char

Specifies an escape character that it used for encoding special characters in the mailbox names in storage. This allows users to use characters in mailboxes names that would otherwise be illegal. For example:

• Maildir layout disallows using the . character, since it's used internally as the folder hierarchy separator.
• The ~ character at the beginning of the mailbox name is disallowed, because of the possibility that it gets expanded to user's home directory.
• The / character can't be used on POSIX filesystems, since it's the directory separator.

The characters are escaped to the mailbox name as <mailbox_list_storage_escape_char><hex>.

INFO

It's possible to use the same character here as for mailbox_list_visible_escape_char.

mailbox_list_utf8

Default	no
Value	boolean

Store mailbox names on disk using UTF-8 instead of modified UTF-7 (mUTF-7).

mailbox_list_validate_fs_names

Default	yes
Value	boolean
See Also	mail_full_filesystem_access

Specifies whether to disallow mailbox names that might be unsafe to use in filesystems or potentially allow bypassing ACL checks:

• / character anywhere in the name (except as a hierarchy separator), unless mailbox list isn't on a filesystem (e.g. index, imapc).
• / as the first character.
• ~ as the first character (so it's not confused as home directory).
• No adjacent / characters.
• No . or .. names between / characters.
• No mailbox_directory_name between / characters.
• No mailbox format-specific internal directories between / characters,
• unless mailbox_directory_name is non-empty. This mainly means the Maildir new, cur and tmp directories in some configurations.

Enabling mail_full_filesystem_access enables also this setting.

mailbox_list_visible_escape_char

Default	[None] The default for imapc storage is ~.
Value	string
See Also	mailbox_list_storage_escape_char

Specifies an escape character that is used for broken or otherwise inaccessible mailbox names. If mailbox name can't be changed reversibly to UTF-8 and back, encode the problematic parts using <mailbox_list_visible_escape_char><hex>in the user-visible UTF-8 name. The mailbox_list_visible_escape_char itself also has to be encoded the same way.

This can be useful with imapc to access mailbox names that aren't valid mUTF-7 charset from remote servers, or if the remote server uses a different hierarchy separator and has folder names containing the local separator.

INFO

It's possible to use the same character here as for mailbox_list_storage_escape_char.

mailbox_root_directory_name

Default	specific to the mail_driver setting
Value	string

Specifies directory name under which all mailbox directories are stored. For example mailboxes with dbox.

mailbox_subscriptions_filename

Default	subscriptions specific Mailbox Formats have different defaults
Value	string
Advanced Setting; this should not normally be changed.

Specifies the filename used for storing mailbox subscriptions.

Variables

You can use several variables in the mail location settings.

See Settings variables for a full list, but the most commonly used ones are:

Variable	Description
%{user}	Full username.
`%{user	username}`
`%{user	domain}`

Directory Hashing

Examples on how to do it:

• %{ user | sha1 % 256 | hex(2)} would give maximum 256 different hashes in range of 00 to ff.

See also Directory hashing

Index Files

Index files are by default stored under the same directory as mails.

You may want to change the index file location if you're using NFS or if you're setting up shared mailboxes.

You can change the index file location with the mail_index_path setting. For example:

mail_driver = maildir
mail_path = ~/Maildir
mail_index_path = /var/indexes/%{user}

The index directories are created automatically, but note that it requires that Dovecot has actually access to create the directories. Either make sure that the index root directory (/var/indexes in the above example) is writable to the logged in user, or create the user's directory with proper permissions before the user logs in.

Index files can be disabled completely with mail_index_path=MEMORY. This is not recommended for production use, as the index files will need to be generated on every access.

Mailbox Root Autodetection

By default the mail_driver and mail_path settings are empty, which means that Dovecot attempts to locate automatically where your mails are. This is done by looking, in order, at:

• ~/mdbox/
• ~/sdbox/
• ~/Maildir/
• ~/mail/.imap/
• ~/mail/inbox
• ~/mail/mbox
• ~/Mail/.imap/
• ~/Mail/inbox
• ~/Mail/mbox

TIP

.imap is a directory, and inbox and mbox are files.

For autodetection to work, one of the above locations has to be populated; when autodetection is active, Dovecot will not attempt to create a mail folder.

It's usually a good idea to explicitly specify where the mails are, even if the autodetection happens to work, in particular to benefit from auto-creation of the folder for new users.

Custom Autodetection

If you need something besides the default autodetection, you can use post-login scripting.

Example Script

#!/bin/sh

if [ -d $HOME/.maildir ]; then
  export MAIL_DRIVER=maildir
  export MAIL_PATH=$HOME/.maildir
else
  export MAIL_DRIVER=mbox
  export MAIL_PATH=$HOME/mail
  export MAIL_INBOX_PATH=/var/mail/$USER
fi
export USERDB_KEYS="$USERDB_KEYS mail_driver mail_path mail_inbox_path"

exec "$@"

Mail Storage Autocreation

If mail_path is set, the path is automatically created if any directories are missing. You'll see something like this if you enable log_debug.

Example for mbox:

Debug: Namespace : /home/user/Mail doesn't exist yet, using default permissions
Debug: Namespace : Using permissions from /home/user/Mail: mode=0700 gid=default

and a Mail/.imap directory will be present once that process has concluded. This is the easiest way to ensure a freshly created user is correctly set up for access via Dovecot.

Home-less Users

Having a home directory for users is highly recommended. At a minimum, Sieve requires a home directory to work.

See Home Directories for Virtual Users for more reasons why it's a good idea, and how to give Dovecot a home directory even if you don't have a "real home directory".

If you really don't want to set any home directory, you can use something like:

mail_driver = maildir
mail_path = /home/%{user}/Maildir

Per-User Mail Locations

It's possible to override the default mail location for specific users by making the userdb return the settings as extra field.

TIP

Note that %{home} doesn't work in the userdb queries or templates. ~/ gets expanded later, so use it instead.

If you have explicit settings inside namespace { .. } they need to be overridden in userdb with namespace/<name>/ prefix. For example namespace/inbox/mail_path instead of simply mail_path.

SQL

userdb sql {
  query = SELECT home, uid, gid, mail_path FROM users WHERE user = '%{user}'
}

LDAP

dovecot.conf

userdb ldap {
  ...
  fields {
    home      = %{ldap:homeDirectory}
    uid       = %{ldap:uidNumber}
    gid       = %{ldap:gidNumber}
    mail_path = %{ldap:mailLocation}
  }
}

Passwd-file

user:{PLAIN}password:1000:1000::/home/user::userdb_mail_driver=mbox userdb_mail_path=~/mail

Mixing Multiple Mailbox Formats

It's possible to use different mailbox formats same user by configuring multiple namespaces. See Namespaces.

Each mailbox format has to live in a different namespace. Mixing mailbox formats within the same namespace is not supported.

Custom Namespace Location

If you need to override namespace's mail location settings, first give it a name (inbox in this example):

namespace inbox {
  [...]
}

Then in the executable script use:

#!/bin/sh

# do the lookup here
mail_driver=mbox
mail_path=$HOME/mail

export USERDB_KEYS="$USERDB_KEYS namespace/inbox/mail_driver namespace/inbox/mail_path"
exec env "NAMESPACE/INBOX/MAIL_DRIVER=$mail_driver" "NAMESPACE/INBOX/MAIL_PATH=$mail_path" "$@"

Finding Your Mail

Before configuring Dovecot, you'll need to know where your mails are located. You should already have an SMTP server installed and configured to deliver mails somewhere, so the easiest way to make Dovecot work is to just use the same location. Otherwise you could create a ~/Maildir directory and configure your SMTP server to use the Maildir format.

First send a test mail to yourself (as your own non-root user):

echo "Hello me" | mail -s "Dovecot test" $USER

Now, find where the mail went. Here's a simple script which checks the most common locations:

for mbox in /var/mail/$USER /var/spool/mail/$USER ~/mbox ~/mail/* ~/*; do
  grep -q "Dovecot test" "$mbox" && echo "mbox: $mbox"
done
grep -q "Dovecot test" ~/Maildir/new/* 2>/dev/null && echo "Maildir: ~/Maildir"

mbox

In most installations your mail went to /var/mail/username file. This file is called INBOX in IMAP world. Since IMAP supports multiple mailboxes, you'll also have to have a directory for them as well. Usually ~/mail is a good choice for this.

For installation such as this, the mail location settings are specified with, where %{user} is replaced with the username that logs in:

• mail_driver = mbox,
• mail_path = ~/mail, and
• mail_inbox_path = /var/mail/%{user}.

Similarly if your INBOX is in ~/mbox, use:

• mail_inbox_path = ~/mbox.

Maildir

Maildir exists almost always in ~/Maildir directory.

The mail location is specified with:

• mail_driver = maildir, and
• mail_path = ~/Maildir.

Troubleshooting

If you can't find the mail, you should check your SMTP server logs and configuration to see where it went or what went wrong.