18
The \fBsieve\-filter\fP command is part of the Sieve implementation for the Dovecot secure
19
IMAP server. Sieve (RFC 5228) is a simple and highly extensible language for filtering
20
e\-mail messages. It can be implemented for any type of mail access protocol, mail
21
architecture and operating system. The language cannot execute external programs and in
22
its basic form it does not provide the means to cause infinite loops, making it suitable
18
The \fBsieve\-filter\fP command is part of the Sieve implementation for the Dovecot secure
19
IMAP server. Sieve (RFC 5228) is a simple and highly extensible language for filtering
20
e\-mail messages. It can be implemented for any type of mail access protocol, mail
21
architecture and operating system. The language cannot execute external programs and in
22
its basic form it does not provide the means to cause infinite loops, making it suitable
23
23
for running securely on mail servers where mail users have no permission run arbitrary programs.
25
25
The Sieve language was originally meant for filtering messages upon delivery. However, there are
29
29
mailbox, making it possible to delete messages, to store them in a different folder and to change
30
30
the assigned IMAP flags and keywords. Attempts to send messages to the outside world are ignored by default
31
31
for obvious reasons, but, using the proper command line options, it is possible to capture outgoing
34
34
The command has three mandatory arguments: the \fIscript\-file\fP argument, which specifies the path of the
35
Sieve script, the \fIsource\-location\fP argument, which specifies the mail storage of the source mailbox
36
(e.g. `maildir:~/Maildir'), and the \fIsource\-mailbox\fP argument, which specifies the name of the source
37
mailbox within the specified mail storage (e.g. `INBOX.Spam').
35
Sieve script, the \fIsource\-location\fP argument, which specifies the mail storage of the source mailbox
36
(e.g. `maildir:~/Maildir'), and the \fIsource\-mailbox\fP argument, which specifies the name of the source
37
mailbox within the specified mail storage (e.g. `INBOX.Spam').
39
39
This tool does not (yet) use Dovecot's configuration file to obtain information on namespaces and the
40
40
location of mailboxes. Therefore, any used namespaces need to be specified on the command line. These
44
44
If no namespaces are defined on the commandline, the source\-location is used as the default mail store
45
45
where the INBOX is located. This means that the keep action could operate on the folder the message
46
46
originates from. In this case the message remains untouched and it is not duplicated, but IMAP flags and
47
keywords can be evaluated and changed with the imap4flags extension . If namespaces are defined explicitly,
48
the source location is available as a namespace with prefix `#src/'.
47
keywords can be evaluated and changed with the imap4flags extension . If namespaces are defined explicitly,
48
the source location is available as a namespace with prefix `#src/'.
50
If no options are specified, the sieve\-filter command runs in a simulation mode in which it only
50
If no options are specified, the sieve\-filter command runs in a simulation mode in which it only
51
51
prints what would be performed, without actually doing anything. Use the \fB\-e\fP option to activate
52
52
true script execution. Also, the source mailbox is opened read\-only by default, so that the source mailbox
53
remains unchanged. Use the \fB\-W\fP to allow changes in the source mailbox.
53
remains unchanged. Use the \fB\-W\fP to allow changes in the source mailbox.
56
Although this is a very useful tool, it can also be very destructive when used improperly. A small
57
bug in your Sieve script in combination with the wrong command line options could cause it to
56
Although this is a very useful tool, it can also be very destructive when used improperly. A small
57
bug in your Sieve script in combination with the wrong command line options could cause it to
58
58
discard (many) more e\-mails than it was supposed to. Therefore, users are advised to read this manual
59
carefully and to use the simulation mode first to check what the script will do.
59
carefully and to use the simulation mode first to check what the script will do.
61
61
\fBMAKING A BACKUP IS IMPERATIVE FOR ANY IMPORTANT MAIL!\fP
65
65
Sieve script decides to do so.
69
69
\fB\-D\fP \fIsource\-action\fP
70
70
By default, the sieve\-filter command does not delete the messages from the source mailbox. This means that
71
71
a copy operation is executed by default and the source mailbox is not altered. The \fIsource\-action\fP
72
72
parameter of the \fB\-D\fP option can take four different values:
75
75
\fBkeep\fP (default)
76
76
Keep messages in source folder. If \fB\-W\fR is specified and the source mailbox is the destination of
77
77
a keep or fileinto action, flags can be changed by the Sieve script. Messages are never duplicated in the
81
81
Flag messages as \\DELETED.
83
83
\fBmove\fP [\fIfolder\fP]
84
84
Move messages to the indicated \fIfolder\fP.
87
87
Expunge messages, meaning that these are removed irreversibly when the tool finishes filtering.
93
Turns on execution mode. By default, the sieve\-filter command runs in simulation mode in which it
93
Turns on execution mode. By default, the sieve\-filter command runs in simulation mode in which it
94
94
changes nothing, meaning that no mailbox is altered in any way and no actions are performed. It only
95
prints what would be done. Using this option the sieve\-filter command becomes active and performs the
95
prints what would be done. Using this option the sieve\-filter command becomes active and performs the
98
98
\fB\-f\fP \fIenvelope\-sender\fP
99
The envelope sender or return path. This is what Sieve's envelope test will compare to when the
100
"from" envelope part is requested. Also, this is where response messages are sent to.
99
The envelope sender or return path. This is what Sieve's envelope test will compare to when the
100
"from" envelope part is requested. Also, this is where response messages are sent to.
102
102
\fB\-m\fP \fIdefault\-mailbox\fP
103
103
The mailbox within the default namespace where the keep action stores the message. This is "INBOX"
106
106
\fB\-Q\fP \fImail\-command\fP
107
Send outgoing e\-mail through the specified program. By default, the sieve\-filter command ignores
107
Send outgoing e\-mail through the specified program. By default, the sieve\-filter command ignores
108
108
Sieve actions such as redirect, reject, vacation and notify, but using this option outgoing messages
109
109
can be fed to the \fBstdin\fP of an external shell command. This option has no effect in simulation
110
110
mode, Unless you really know what you are doing, \fBDO NOT USE THIS TO FEED MAIL TO SENDMAIL!\f.
122
122
Enables write access to the source mailbox. This allows deleting the messages from the source mailbox
123
and changing the assigned IMAP flags and keywords.
123
and changing the assigned IMAP flags and keywords.
125
125
\fB\-x\fP "\fIextension extension ...\fP"
126
126
Set the available extensions. The parameter is a space\-separated list of the active extensions. By
127
127
prepending the extension identifiers with \fB+\fP or \fB\-\fP, extensions can be included or excluded
128
relative to the default set of extensions. If no extensions have a \fB+\fP or \fB\-\fP prefix, only
129
those extensions that are explicitly listed will be enabled. Unknown extensions are ignored and a
130
warning is produced. By default, all supported extensions are available, except for deprecated extensions
128
relative to the default set of extensions. If no extensions have a \fB+\fP or \fB\-\fP prefix, only
129
those extensions that are explicitly listed will be enabled. Unknown extensions are ignored and a
130
warning is produced. By default, all supported extensions are available, except for deprecated extensions
131
131
or those that are still under development.
133
133
For example \fB\-x\fP "+imapflags \-enotify" will enable the deprecated imapflags extension along with all
added
removed
sieve/doc/man/sieve-filter.1
