Manage Per-User Sieve Scripts with doveadm sieve

A mail filter you cannot see is a filter you cannot trust, and doveadm sieve lets you inspect and manage one user's Sieve scripts from the shell. You will list them, upload a new script from standard input, retrieve a copy, rename it, and control which script is active. Allow about 15 minutes for a first run, plus time to check the script's effect on a test mailbox.

1. Check the installation and version boundary

The commands come from Pigeonhole, the Dovecot project component that adds Sieve and ManageSieve support. The local manual page is labelled Pigeonhole for Dovecot v2.4, while the installed dovecot-core package on this machine is version 2.3.21+dfsg1-2ubuntu6.5. A manual page and binary from different releases can have different options.

$ command -v doveadm
/usr/bin/doveadm
$ dpkg-query -W -f='${Package} ${Version}\n' dovecot-core
dovecot-core 1:2.3.21+dfsg1-2ubuntu6.5
$ doveadm help 2>&1 | grep -E '^  sieve[[:space:]]' || echo 'sieve is not listed'

On the reference machine, the installed help does not list a Sieve command, and it also reports a permission error while trying to reach a Dovecot statistics socket. That is evidence this dovecot-core-only installation is not ready to run these examples.

Install or enable the matching Pigeonhole package and configure Dovecot before continuing. Use the manual page shipped with that installation if its version differs.

2. Select one user and list the scripts

Use -u for a single mailbox. The value is a Dovecot user name, often an email address. The script name is the one visible to ManageSieve clients. For scripts stored on disk, the manpage says to omit the .sieve suffix.

$ doveadm sieve list -u '[email protected]'
$ doveadm -f table sieve list -u '[email protected]'

The first form gives an overview of the user's existing scripts. The second asks for table formatting, which is easier to scan when the command supports that formatter. Do not guess a script name from a filename. Use the list result, then copy the exact name into later commands.

3. Retrieve a backup before changing a script

sieve get writes the named script to standard output. Redirect it to a new local file, and avoid a destination that already holds your only backup.

$ umask 077
$ doveadm sieve get -u '[email protected]' 'vacation' > /tmp/alice-vacation.sieve
$ test -s /tmp/alice-vacation.sieve && echo 'backup written'
backup written

The umask makes a newly created backup private to its owner. Treat the file as sensitive, because Sieve rules can reveal addresses, subjects and business processes. Keep it only as long as you need it.

4. Upload a new script, then activate it

sieve put reads the script from standard input and stores it under the supplied name only if it compiles successfully. Start with a new name while testing. The -a option makes the uploaded script active immediately, which changes filtering at delivery.

$ cat > /tmp/alice-test.sieve <<'SIEVE'
require ["fileinto"];
if header :contains "X-Training-Mail" "yes" {
  fileinto "Training";
}
SIEVE
$ doveadm sieve put -u '[email protected]' 'training-test' < /tmp/alice-test.sieve
$ doveadm sieve list -u '[email protected]'

You do not need sudo for the local temporary file. The final command is the verification step: confirm that training-test appears. A compile failure should leave the new script unapplied, so fix the Sieve source and retry.

When you are ready to switch delivery to an existing script, activate it explicitly:

$ doveadm sieve activate -u '[email protected]' 'training-test'
$ doveadm sieve list -u '[email protected]'

5. Rename or delete after checking the active state

Renaming keeps the script and changes the name that clients and later commands use:

$ doveadm sieve rename -u '[email protected]' 'training-test' 'training'
$ doveadm sieve list -u '[email protected]'

To undo a rename, reverse the two names. Before deletion, retrieve a backup and confirm the target is not active. The normal command refuses to delete an active script.

$ doveadm sieve get -u '[email protected]' 'old-test' > /tmp/alice-old-test.sieve
$ doveadm sieve delete -u '[email protected]' 'old-test'
$ doveadm sieve list -u '[email protected]'

Do not use -a in a cleanup command unless you have deliberately chosen what should happen to newly delivered mail.

6. Work across users only with an explicit plan

-A runs a command for all users discovered through the user database. The manual warns that iterating SQL or LDAP users depends on correctly configured iteration queries or filters. It also warns against combining -A with a system-user database that includes low-UID accounts.

Prefer a tested -u command for one mailbox, and review the user database before any bulk operation.

-S selects a local Unix socket or a remote hostname:port.

Global -D enables debug output, while -v adds verbosity and a progress counter. Keep debug output out of shared logs if it may expose mailbox names or configuration.