### Install Dovecot under home directory

Source: https://github.com/dovecot/documentation/blob/main/docs/core/config/rootless.md

Build and install Dovecot under the user's home directory. Run these commands from the Dovecot source directory. After installation, Dovecot is started with ~/dovecot/sbin/dovecot and an example configuration is placed in ~/dovecot/etc/dovecot/dovecot.conf.

```sh
./configure --prefix=$HOME/dovecot
make
make install
```

--------------------------------

### Expected directory permissions after setup

Source: https://github.com/dovecot/documentation/blob/main/docs/core/config/shared_mailboxes.md

Example directory permissions after applying the group-suid setup. The domain directory is group-writable with setgid, while the user subdirectory is private to the user.

```text
drwxrwsr-x 3 user dovemail 60 Oct 24 12:04 domain.example.com/
drwx--S--- 3 user user 60 Oct 24 12:04 domain.example.com/user/
```

--------------------------------

### Insert example values

Source: https://github.com/dovecot/documentation/blob/main/docs/howto/virtual/postgresql.md

Insert example data for domains and users.

```sql
insert into transport (domain, transport) values ('domain.org', 'virtual:');
insert into transport (domain, transport) values ('foo.org', 'virtual:');
insert into users (userid, uid, gid, home) values ('user@domain.org', 1001, 1001, 'domain.org/mails/user');
insert into users (userid, uid, gid, home) values ('user2@domain.org', 1001, 1001, 'domain.org/mails/user2');
insert into users (userid, uid, gid, home) values ('user@foo.org', 1002, 1002, 'foo.org/mails/user');
insert into virtual (address, userid) values ('foo@foo.org', 'user@foo.org');
```

--------------------------------

### Configuration: Example master user setup

Source: https://github.com/dovecot/documentation/blob/main/docs/core/config/auth/master_users.md

Sets up master user authentication with a passwd-file passdb, enabling master login and continuing to verify the login user's existence. Must be placed in dovecot.conf. Also includes userdb configuration.

```doveconf
auth_master_user_separator = *

passdb passwd-file {
  passwd_file_path = /etc/dovecot/passwd.masterusers
  master = yes
  result_success = continue
}

userdb passwd {
}

```

--------------------------------

### AUTHENTICATE command example with response

Source: https://github.com/dovecot/documentation/blob/main/docs/core/config/sieve/managesieve.md

Example of the AUTHENTICATE command and the server's response after successful login.

```text
AUTHENTICATE "PLAIN" "<base64-encoded credentials>"
OK "Logged in."
```

--------------------------------

### Lua script for %{lua_file} example (get_home.lua)

Source: https://github.com/dovecot/documentation/blob/main/docs/core/plugins/mail_lua.md

Example Lua script that defines a get_home function returning a home directory path. The comment warns this is not a good practice and is for example purposes only.

```lua
-- This is not a good way to do this, provided here for example
-- purposes only. Do not use this.

local function get_home(user)
  return "/home/" .. user
end
```

--------------------------------

### Set up Python environment and install dependencies

Source: https://github.com/dovecot/documentation/blob/main/docs/developers/design/dcrypt.md

Sets up a local Python environment and installs the required dependencies (asn1 and cryptography) for running dcrypt-decrypt.py.

```sh
# Optional but recommended: Create a virtual environment for the necessary
# python dependencies to run this script.
python -m venv venv
source venv/bin/activate
# Install the dependencies.
pip install asn1 cryptography
```

--------------------------------

### Linux /etc/pam.d/dovecot example

Source: https://github.com/dovecot/documentation/blob/main/docs/core/config/auth/databases/pam.md

Example PAM configuration for Linux using pam_unix.so for authentication and account management. Place this in /etc/pam.d/dovecot.

```pam
auth      required        pam_unix.so nullok
account   required        pam_unix.so
```

--------------------------------

### fts-flatcurve configuration example with optional settings

Source: https://github.com/dovecot/documentation/blob/main/docs/core/plugins/fts_flatcurve.md

Full configuration example showing all optional settings with their default values. These are listed for documentation; most users should not need to override them. Note substring_search defaults to no in this example, but the plugin supports substring matches on by default.

```doveconf
mail_plugins {
  fts = yes
  fts_flatcurve = yes
}

fts flatcurve {
  # All of these are optional, and indicate the default values.
  # They are listed here for documentation purposes; most people should not
  # need to define/override in their config.
  commit_limit = 500
  min_term_size = 2
  optimize_limit = 10
  rotate_count = 5000
  rotate_time = 5000
  substring_search = no
}
```

--------------------------------

### static passdb with allow_nets and local keyword

Source: https://github.com/dovecot/documentation/blob/main/docs/core/config/auth/passdb.md

Static password database example for a Postfix/LMTP delivery setup. The 'local' keyword is required so Postfix can verify email accounts over Unix sockets, avoiding the error about user not existing.

```doveconf
passdb static {
  password = test
  fields {
    allow_nets = local,127.0.0.1/32
  }
}
```

--------------------------------

### userdb static example

Source: https://github.com/dovecot/documentation/blob/main/docs/core/config/auth/databases/static.md

Example static userdb configuration that sets uid, gid, and home directory using a variable for the username.

```doveconf
userdb static {
  fields {
    uid = 500
    gid = 500
    home = /home/%{user}
  }
}
```

--------------------------------

### EC parameters header example

Source: https://github.com/dovecot/documentation/blob/main/docs/core/plugins/mail_crypt.md

Example of EC parameters that may appear before the private key.

```text
-----BEGIN EC PARAMETERS-----
BgUrgQQACg==
-----END EC PARAMETERS-----
```

--------------------------------

### Example /doveadm/v1 response

Source: https://github.com/dovecot/documentation/blob/main/docs/core/admin/doveadm.md

Example JSON response from the /doveadm/v1 endpoint, showing the command list and their parameters.

```json
[
  {
    "command": "reload",
    "parameters": []
  },
  {
    "command": "statsDump",
    "parameters": [
      {"name": "socketPath", "type": "string"},
      {"name": "reset", "type": "boolean"},
      {"name": "fields", "type": "string"}
    ]
  },
  {
    "command": "fsDelete",
    "parameters": [
      {"name": "recursive", "type": "boolean"},
      {"name": "maxParallel", "type": "integer"},
      {"name": "filterName", "type": "string"},
      {"name": "path", "type": "array"}
    ]
  }
]
```

--------------------------------

### Mac OS X /etc/pam.d/dovecot example

Source: https://github.com/dovecot/documentation/blob/main/docs/core/config/auth/databases/pam.md

Example PAM configuration for Mac OS X using pam_opendirectory.so and pam_nologin.so. Place in /etc/pam.d/dovecot.

```pam
auth        required       pam_opendirectory.so try_first_pass
account     required       pam_nologin.so
account     required       pam_opendirectory.so
password    required       pam_opendirectory.so
```

--------------------------------

### Preview static documentation with npm run docs:preview

Source: https://github.com/dovecot/documentation/blob/main/README.md

Run this command to serve the statically generated documentation locally for previewing.

```sh
npm run docs:preview
```

--------------------------------

### Execute imap session

Source: https://github.com/dovecot/documentation/blob/main/docs/core/man/doveadm-exec.1.md

Example of starting a pre-authenticated imap session for a system user.

```sh
doveadm exec imap
```

--------------------------------

### Start imap in PREAUTH mode

Source: https://github.com/dovecot/documentation/blob/main/docs/developers/debugging.md

These commands start the imap executable in PREAUTH mode, bypassing login and authorization. Use the appropriate path for your installation or source tree. This also works for pop3 and managesieve.

```sh
/usr/libexec/dovecot/imap -u <username>
```

```sh
src/imap/imap -u <username>
```

```sh
doveadm exec imap -u <username>
```

--------------------------------

### Connect to ManageSieve with gnutls-cli --starttls

Source: https://github.com/dovecot/documentation/blob/main/docs/core/config/sieve/managesieve.md

Use this command to start a plain text connection to the ManageSieve server, which will present its capabilities. If STARTTLS is listed, you can proceed with the STARTTLS command.

```sh
gnutls-cli --starttls -p <port> <host>
```

--------------------------------

### Execute imap session for a specific user

Source: https://github.com/dovecot/documentation/blob/main/docs/core/man/doveadm-exec.1.md

Example of starting a pre-authenticated imap session for a specific username as an administrator.

```sh
doveadm exec imap -u username
```

--------------------------------

### Request examples for /doveadm/v1

Source: https://github.com/dovecot/documentation/blob/main/docs/core/admin/doveadm.md

Two equivalent ways to send an authenticated GET request to the /doveadm/v1 endpoint using Basic authentication.

```sh
curl -H "Authorization: Basic <base64 doveadm:doveadm_password>" http://host:port/doveadm/v1
```

```sh
curl -u doveadm:password http://host:port/doveadm/v1
```

--------------------------------

### Running a command: quota get

Source: https://github.com/dovecot/documentation/blob/main/docs/developers/design/doveadm_protocol.md

Command format: flags<tab>username<tab>command name[<tab>parameter...]. Flags can be empty, 'v' (verbose), or 'D' (debug). Example gets quota for user tss; server replies with values and '+'.

```protocol
C: <TAB>tss<TAB>quota<TAB>get
S: user STORAGE 1814    -       0       user    MESSAGE 6       -       0
S: +
```

--------------------------------

### Run Dovecot imap binary with gdb

Source: https://github.com/dovecot/documentation/blob/main/docs/developers/debugging.md

Starts the imap binary under gdb and enables interactive debugging. After a crash, use 'bt full' to get a backtrace.

```text
# gdb --args /usr/local/libexec/dovecot/imap -u user@domain

...

(gdb) r
Starting program: /usr/local/libexec/dovecot/imap
* PREAUTH [CAPABILITY IMAP4rev1 SORT THREAD=REFERENCES MULTIAPPEND UNSELECT
LITERAL+ IDLE CHILDREN LISTEXT LIST-SUBSCRIBED] Logged in as user
```

--------------------------------

### LISTSCRIPTS command example

Source: https://github.com/dovecot/documentation/blob/main/docs/core/config/sieve/managesieve.md

Lists the scripts on the server. After a successful upload, the script should be listed.

```text
LISTSCRIPTS
"example"
OK "Listscripts completed."
```

--------------------------------

### Run Dovecot executable with libtool for debugging

Source: https://github.com/dovecot/documentation/blob/main/docs/developers/debugging.md

Use libtool to run an executable from the source tree without installing. The example runs gdb on src/imap/imap. An alias for libtool's execute mode is also provided.

```sh
libtool e gdb --args src/imap/imap
```

```bash
alias lgdb='libtool --mode=execute gdb'
```

--------------------------------

### Install dependencies with npm

Source: https://github.com/dovecot/documentation/blob/main/README.md

Run this command from the project root to install all required dependencies. Use any compatible package manager (pnpm, yarn, bun) instead of npm if preferred.

```sh
npm install
```

--------------------------------

### Build static documentation with npm run docs:build

Source: https://github.com/dovecot/documentation/blob/main/README.md

Run this command to generate the static documentation. The output is placed in the docs/.vitepress/dist directory.

```sh
npm run docs:build
```

--------------------------------

### IMAP Command Statistics - dovecot.conf metric definitions

Source: https://github.com/dovecot/documentation/blob/main/docs/core/config/statistics.md

Example configuration for IMAP command statistics. Defines metrics for IMAP SELECT failures, storage HTTP GETs, and per-command metrics for successful commands using `group_by`.

```doveconf
metric imap_select_no {
  filter = event=imap_command_finished AND cmd_name=SELECT AND \
      tagged_reply_state=NO
}

metric imap_select_no_notfound {
  filter = event=imap_command_finished AND cmd_name=SELECT AND \
      tagged_reply="NO*Mailbox doesn't exist:*"
}

metric storage_http_gets {
  filter = event=http_request_finished AND category=storage AND \
      method=get
}

# generate per-command metrics on successful commands
metric imap_command {
  filter = event=imap_command_finished AND tagged_reply_state=OK
  group_by cmd_name {
  }
}
```

--------------------------------

### Create tables and views

Source: https://github.com/dovecot/documentation/blob/main/docs/howto/virtual/postgresql.md

Create the transport, users, and virtual tables, and the postfix_mailboxes and postfix_virtual views.

```sql
CREATE TABLE transport (
    domain VARCHAR(128) NOT NULL,
    transport VARCHAR(128) NOT NULL,
    PRIMARY KEY (domain)
);

CREATE TABLE users (
    userid VARCHAR(128) NOT NULL,
    password VARCHAR(128),
    realname VARCHAR(128),
    uid INTEGER NOT NULL,
    gid INTEGER NOT NULL,
    home VARCHAR(128),
    mail VARCHAR(255),
    PRIMARY KEY (userid)
);

CREATE TABLE virtual (
    address VARCHAR(255) NOT NULL,
    userid VARCHAR(255) NOT NULL,
    PRIMARY KEY (address)
);

create view postfix_mailboxes as
    select userid, home||'/' as mailbox from users
    union all
    select domain as userid, 'dummy' as mailbox from transport;

create view postfix_virtual as
    select userid, userid as address from users
    union all
     select userid, address from virtual;
```

--------------------------------

### Configuration Example

Source: https://github.com/dovecot/documentation/blob/main/docs/core/plugins/push_notification_lua.md

Example configuration for enabling the Lua push notification plugin in Dovecot.

```APIDOC
## Configuration Example

### Description
Example configuration for enabling the Lua push notification plugin in Dovecot.

### Configuration

```doveconf[dovecot.conf]
mail_plugins {
  mail_lua = yes
  notify = yes
  push_notification = yes
  push_notification_lua = yes
}

push_notification lua {
  lua_file = /path/to/lua/script
  lua_settings {
    extra_param = %{userdb:extra_param}
  }
}
```
```

--------------------------------

### Install required packages

Source: https://github.com/dovecot/documentation/blob/main/docs/howto/virtual/postgresql.md

Install Postfix, SASL, PostgreSQL, and Dovecot packages on Debian.

```sh
apt-get install postfix-pgsql sasl2-bin libsasl2-modules postgresql \
  libpam-pgsql dovecot-pgsql dovecot-imapd dovecot-pop3d
```

--------------------------------

### Enable and configure extlists in dovecot.conf

Source: https://github.com/dovecot/documentation/blob/main/docs/core/config/sieve/extensions/extlists.md

Configuration example for enabling the extlists extension and setting up external lists with dict proxies. Includes a global max lookup size and a per-list override. The list 'tag:example.com,2025-02-26:BadFileExts' limits lookups to 10 bytes.

```doveconf
# Use extlists
sieve_extensions {
  extlists = yes
}

# No value looked up from a list may exceed 512 bytes, or it will forcibly not
# match
sieve_extlists_list_max_lookup_size = 512

# The default addressbook stored in a proxied dict
sieve_extlists_list :addrbook:default {
  dict proxy {
    name = addressbook
  }
}

sieve_extlists_list tag:example.com,2025-02-26:BadFileExts {
  dict proxy {
    name = bad_file_extensions
  }

  # Limit lookups to 10 bytes
  max_lookup_size = 10B
}

```

--------------------------------

### BEGIN command syntax

Source: https://github.com/dovecot/documentation/blob/main/docs/developers/design/dict_protocol.md

Starts a dict transaction with the given ID. The command format is 'B<id>TAB<user>'. Note that transaction commands do not have replies except for COMMIT.

```text
C: B<id>TAB<user>
```

--------------------------------

### Sample Dovecot init.d script

Source: https://github.com/dovecot/documentation/blob/main/docs/installation/startup_scripts.md

Place this script in /etc/init.d/dovecot and change the DAEMON path if needed. It supports start, stop, reload, restart, and force-reload actions, and uses the master.pid file to determine if Dovecot is running. The script is public domain and should work in all operating systems.

```bash
### BEGIN INIT INFO
# Provides:          dovecot
# Required-Start:    $local_fs $remote_fs $network $syslog $time
# Required-Stop:     $local_fs $remote_fs $network $syslog
# Should-Start:      postgresql mysql slapd winbind
# Should-Stop:       postgresql mysql slapd winbind
# Default-Start:     2 3 4 5
# Default-Stop:      0 1 6
# Short-Description: Dovecot init script
# Description:       Init script for dovecot services
### END INIT INFO

# Example /etc/init.d/dovecot script. Change DAEMON if necessary.
# License is public domain.

DAEMON=/usr/local/sbin/dovecot

# Uncomment to allow Dovecot daemons to produce core dumps.
#ulimit -c unlimited

test -x $DAEMON || exit 1
set -e

base_dir=`$DAEMON config -h base_dir`
pidfile=$base_dir/master.pid

if test -f $pidfile; then
  running=yes
else
  running=no
fi

case "$1" in
start)
  echo -n "Starting Dovecot"
  $DAEMON
  echo "."
  ;;
stop)
  if test $running = yes; then
    echo "Stopping Dovecot"
    kill `cat $pidfile`
    echo "."
  else
    echo "Dovecot is already stopped."
  fi
  ;;
reload)
  if test $running = yes; then
    echo -n "Reloading Dovecot configuration"
    kill -HUP `cat $pidfile`
    echo "."
  else
    echo "Dovecot isn't running."
  fi
  ;;
restart|force-reload)
  echo -n "Restarting Dovecot"
  if test $running = yes; then
    kill `cat $pidfile`
    sleep 1
  fi
  $DAEMON
  echo "."
  ;;
*)
  echo "Usage: /etc/init.d/dovecot {start|stop|reload|restart|force-reload}" >&2
  exit 1
  ;;
esac

exit 0
```

--------------------------------

### url_rewrite callback example

Source: https://github.com/dovecot/documentation/blob/main/README.md

Example of the `url_rewrite` callback. Receives the original URL and returns the modified URL.

```javascript
url_rewrite: (url) => { return url + '.foo' }
```

--------------------------------

### Example Virtual User Home Directory Structure

Source: https://github.com/dovecot/documentation/blob/main/docs/howto/virtual/postfix.md

Shows the expected files and directories in a virtual user's home directory under /var/vmail/<domain>/<user>/.

```text
-rw------- 1 vmail vmail 1489 2010-03-03 19:30 .dovecot.sieve
-rw------- 1 vmail vmail 2897 2010-03-14 12:22 .dovecot.svbin
drwx--S--- 4 vmail vmail 4096 2010-03-17 20:15 maildir
drwx--S--- 4 vmail vmail 4096 2010-03-14 13:31 public
```

--------------------------------

### markdown_extend close callback example

Source: https://github.com/dovecot/documentation/blob/main/README.md

Example of the `close` callback for the `markdown_extend` configuration. Returns a closing tag.

```javascript
close: (mode, env) => { return '' }
```

--------------------------------

### markdown_extend body callback example

Source: https://github.com/dovecot/documentation/blob/main/README.md

Example of the `body` callback for the `markdown_extend` configuration. Returns body text.

```javascript
body: (mode, env) => { return '' }
```

--------------------------------

### Configuration: SQL master passdb example

Source: https://github.com/dovecot/documentation/blob/main/docs/core/config/auth/master_users.md

Shows configuring a master passdb using an SQL query. The master user is selected from the users table where master_user is true. Also includes base SQL driver and userdb. Replace the query with a valid query and configure the SQL driver.

```doveconf
sql_driver = mysql
mysql localhost {
}

auth_master_user_separator = *

passdb db1 {
  driver = sql
  query = SELECT password FROM users WHERE userid = '%{user}' and master_user = true
  master = yes
  result_success = continue
}

passdb db2 {
  driver = sql
  query = # ...
}

userdb sql {
  query = # ...
}

```