. /////////////////////////////////////////////////////////////////////////////
. This is the primary source of the document that describes Exim's filtering
. facilities. It is an xfpt document that is converted into DocBook XML for
. /////////////////////////////////////////////////////////////////////////////
. This is the primary source of the document that describes Exim's filtering
. facilities. It is an xfpt document that is converted into DocBook XML for
toc_chapter_blanks="yes,yes"
toc_title="Exim's interfaces to mail filtering"
?>
toc_chapter_blanks="yes,yes"
toc_title="Exim's interfaces to mail filtering"
?>
. /////////////////////////////////////////////////////////////////////////////
. /////////////////////////////////////////////////////////////////////////////
. /////////////////////////////////////////////////////////////////////////////
. /////////////////////////////////////////////////////////////////////////////
<author><firstname>Philip</firstname><surname>Hazel</surname></author>
<authorinitials>PH</authorinitials>
<revhistory><revision>
<author><firstname>Philip</firstname><surname>Hazel</surname></author>
<authorinitials>PH</authorinitials>
<revhistory><revision>
-facilities, and is copyright © University of Cambridge 2007. It
-corresponds to Exim version 4.67.
+facilities, and is copyright © The Exim Maintainers ©year(). It
+corresponds to Exim version &version().
Most Unix mail transfer agents (programs that deliver mail) permit individual
users to specify automatic forwarding of their mail, usually by placing a list
of forwarding addresses in a file called &_.forward_& in their home
Most Unix mail transfer agents (programs that deliver mail) permit individual
users to specify automatic forwarding of their mail, usually by placing a list
of forwarding addresses in a file called &_.forward_& in their home
It is important to realize that, in Exim, no deliveries are actually made while
a filter or traditional &_.forward_& file is being processed. Running a filter
or processing a traditional &_.forward_& file sets up future delivery
It is important to realize that, in Exim, no deliveries are actually made while
a filter or traditional &_.forward_& file is being processed. Running a filter
or processing a traditional &_.forward_& file sets up future delivery
A filter file is normally installed under the name &_.forward_& in your home
directory &-- it is distinguished from a conventional &_.forward_& file by its
first line (described below). However, the file name is configurable, and some
A filter file is normally installed under the name &_.forward_& in your home
directory &-- it is distinguished from a conventional &_.forward_& file by its
first line (described below). However, the file name is configurable, and some
Testing a filter file before installation cannot find every potential problem;
for example, it does not actually run commands to which messages are piped.
Some &"live"& tests should therefore also be done once a filter is installed.
Testing a filter file before installation cannot find every potential problem;
for example, it does not actually run commands to which messages are piped.
Some &"live"& tests should therefore also be done once a filter is installed.
The filtering commands for Sieve and Exim filters are completely different in
syntax and semantics. The Sieve mechanism is defined in RFC 3028; in the next
chapter we describe how it is integrated into Exim. The subsequent chapter
The filtering commands for Sieve and Exim filters are completely different in
syntax and semantics. The Sieve mechanism is defined in RFC 3028; in the next
chapter we describe how it is integrated into Exim. The subsequent chapter
This chapter does not contain a description of Sieve, since that can be found
in RFC 3028, which should be read in conjunction with these notes.
This chapter does not contain a description of Sieve, since that can be found
in RFC 3028, which should be read in conjunction with these notes.
The Exim Sieve implementation offers the core as defined by RFC 3028,
comparison tests, the subaddress parameter, the &*copy*&, &*envelope*&,
&*fileinto*&, &*notify*&, and &*vacation*& extensions, but not the &*reject*&
The Exim Sieve implementation offers the core as defined by RFC 3028,
comparison tests, the subaddress parameter, the &*copy*&, &*envelope*&,
&*fileinto*&, &*notify*&, and &*vacation*& extensions, but not the &*reject*&
-extension. Exim does not support message delivery notifications (MDNs), so
-adding it just to the Sieve filter (as required for &*reject*&) makes little
-sense.
+extension.
+.new
+Exim did not support message delivery notifications (MDNs) when Sieve handling
+was introduced, so &*reject*& (which need them) could not be supported.
If the system administrator has set things up as suggested in the Exim
specification, and you use &(keep)& or &(fileinto)& to save a mail into a
folder, absolute files are stored where specified, relative files are stored
If the system administrator has set things up as suggested in the Exim
specification, and you use &(keep)& or &(fileinto)& to save a mail into a
folder, absolute files are stored where specified, relative files are stored
RFC 3028 does not specify what happens if a string denoting a header field does
not contain a valid header name, for example, it contains a colon. This
implementation generates an error instead of ignoring the header field in order
RFC 3028 does not specify what happens if a string denoting a header field does
not contain a valid header name, for example, it contains a colon. This
implementation generates an error instead of ignoring the header field in order
The &*exists*& test succeeds only if all the specified headers exist. RFC 3028
does not explicitly specify what happens on an empty list of headers. This
implementation evaluates that condition as true, interpreting the RFC in a
The &*exists*& test succeeds only if all the specified headers exist. RFC 3028
does not explicitly specify what happens on an empty list of headers. This
implementation evaluates that condition as true, interpreting the RFC in a
Some MUAs process invalid base64 encoded data, generating junk. Others ignore
junk after seeing an equal sign in base64 encoded data. RFC 2047 does not
specify how to react in this case, other than stating that a client must not
Some MUAs process invalid base64 encoded data, generating junk. Others ignore
junk after seeing an equal sign in base64 encoded data. RFC 2047 does not
specify how to react in this case, other than stating that a client must not
A header may contain multiple addresses. RFC 3028 does not explicitly specify
how to deal with them, but since the address test checks if anything matches
anything else, matching one address suffices to satisfy the condition. That
A header may contain multiple addresses. RFC 3028 does not explicitly specify
how to deal with them, but since the address test checks if anything matches
anything else, matching one address suffices to satisfy the condition. That
RFC 3028 does not specify whether &(fileinto)& should try to create a mail
folder if it does not exist. This implementation allows the sysadmin to
configure that aspect using the &(appendfile)& transport options
RFC 3028 does not specify whether &(fileinto)& should try to create a mail
folder if it does not exist. This implementation allows the sysadmin to
configure that aspect using the &(appendfile)& transport options
Sieve scripts are supposed to be interoperable between servers, so this
implementation does not allow mail to be redirected to unqualified addresses,
because the domain would depend on the system being used. On systems with
Sieve scripts are supposed to be interoperable between servers, so this
implementation does not allow mail to be redirected to unqualified addresses,
because the domain would depend on the system being used. On systems with
There has been confusion if the string arguments to &(require)& are to be
matched case-sensitively or not. This implementation matches them with the
match type &(:is)& (default, see section 2.7.1 of the RFC) and the comparator
There has been confusion if the string arguments to &(require)& are to be
matched case-sensitively or not. This implementation matches them with the
match type &(:is)& (default, see section 2.7.1 of the RFC) and the comparator
There is a mistake in RFC 3028: the suffix G denotes gibi-, not tebibyte.
The mistake is obvious, because RFC 3028 specifies G to denote 2^30
(which is gibi, not tebi), and that is what this implementation uses as
There is a mistake in RFC 3028: the suffix G denotes gibi-, not tebibyte.
The mistake is obvious, because RFC 3028 specifies G to denote 2^30
(which is gibi, not tebi), and that is what this implementation uses as
A complete list of the available variables is given in the Exim documentation.
This shortened list contains the ones that are most likely to be useful in
personal filter files:
A complete list of the available variables is given in the Exim documentation.
This shortened list contains the ones that are most likely to be useful in
personal filter files:
There are ten user variables with names &$n0$& &-- &$n9$& that can be
incremented by the &(add)& command (see section &<<SECTadd>>&). These can be
used for &"scoring"& messages in various ways. If Exim is configured to run a
There are ten user variables with names &$n0$& &-- &$n9$& that can be
incremented by the &(add)& command (see section &<<SECTadd>>&). These can be
used for &"scoring"& messages in various ways. If Exim is configured to run a
The contents of your filter file should not make any assumptions about the
current directory. It is best to use absolute paths for file names; you can
normally make use of the &$home$& variable to refer to your home directory. The
The contents of your filter file should not make any assumptions about the
current directory. It is best to use absolute paths for file names; you can
normally make use of the &$home$& variable to refer to your home directory. The
The filter commands that are described in subsequent sections are listed
below, with the section in which they are described in brackets:
The filter commands that are described in subsequent sections are listed
below, with the section in which they are described in brackets:
&` [log `&<&'log file name'&>&`]`&
&` [once `&<&'note file name'&>&`]`&
&` [once_repeat `&<&'time interval'&>&`]`&
&` [log `&<&'log file name'&>&`]`&
&` [once `&<&'note file name'&>&`]`&
&` [once_repeat `&<&'time interval'&>&`]`&
&`e.g. mail text "Your message about $h_subject: has been received"`&
.endd
Each <&'address-list'&> can contain a number of addresses, separated by commas,
&`e.g. mail text "Your message about $h_subject: has been received"`&
.endd
Each <&'address-list'&> can contain a number of addresses, separated by commas,
&`e.g. logwrite "$tod_log $message_id processed"`&
.endd
It is possible to have more than one &(logfile)& command, to specify writing to
&`e.g. logwrite "$tod_log $message_id processed"`&
.endd
It is possible to have more than one &(logfile)& command, to specify writing to
-different log files in different circumstances. Writing takes place at the end
+different log files in different circumstances.
+A previously opened log is closed on a subsequent &(logfile)& command.
+Writing takes place at the end
of the file, and a newline character is added to the end of each string if
there isn't one already there. Newlines can be put in the middle of the string
by using the &"\n"& escape sequence. Lines from simultaneous deliveries may get
of the file, and a newline character is added to the end of each string if
there isn't one already there. Newlines can be put in the middle of the string
by using the &"\n"& escape sequence. Lines from simultaneous deliveries may get
There are a number of conditions that operate on text strings, using the words
&"begins"&, &"ends"&, &"is"&, &"contains"& and &"matches"&. If you want to
apply the same test to more than one header line, you can easily concatenate
There are a number of conditions that operate on text strings, using the words
&"begins"&, &"ends"&, &"is"&, &"contains"& and &"matches"&. If you want to
apply the same test to more than one header line, you can easily concatenate
library, which provides regular expressions that are compatible with Perl.
The match succeeds if the regular expression matches any part of the first
library, which provides regular expressions that are compatible with Perl.
The match succeeds if the regular expression matches any part of the first
You can use the &(delivered)& condition to test whether or not any previously
obeyed filter commands have set up a significant delivery. For example:
.code
You can use the &(delivered)& condition to test whether or not any previously
obeyed filter commands have set up a significant delivery. For example:
.code
The condition &(error_message)& is true if the incoming message is a bounce
(mail delivery error) message. Putting the command
.code
The condition &(error_message)& is true if the incoming message is a bounce
(mail delivery error) message. Putting the command
.code
There is a facility for looping through a list of addresses and applying a
condition to each of them. It takes the form
.display
There is a facility for looping through a list of addresses and applying a
condition to each of them. It takes the form
.display
It is quite common for people who have mail accounts on a number of different
systems to forward all their mail to one system, and in this case a check for
personal mail should test all their various mail addresses. To allow for this,
It is quite common for people who have mail accounts on a number of different
systems to forward all their mail to one system, and in this case a check for
personal mail should test all their various mail addresses. To allow for this,
$message_headers does not contain "\nList-Owner:" and
$message_headers does not contain "\nList-Archive:" and
(
$message_headers does not contain "\nList-Owner:" and
$message_headers does not contain "\nList-Archive:" and
(
There are two conditions that are intended mainly for use in system filter
files, but which are available in users' filter files as well. The condition
&(first_delivery)& is true if this is the first process that is attempting to
There are two conditions that are intended mainly for use in system filter
files, but which are available in users' filter files as well. The condition
&(first_delivery)& is true if this is the first process that is attempting to
The system administrator can configure Exim so that users can set up variants
on their email addresses and handle them separately. Consult your system
administrator or local documentation to see if this facility is enabled on your
The system administrator can configure Exim so that users can set up variants
on their email addresses and handle them separately. Consult your system
administrator or local documentation to see if this facility is enabled on your
As was explained above, filtering just sets up addresses for delivery &-- no
deliveries are actually done while a filter file is active. If any of the
generated addresses subsequently suffers a delivery failure, an error message
As was explained above, filtering just sets up addresses for delivery &-- no
deliveries are actually done while a filter file is active. If any of the
generated addresses subsequently suffers a delivery failure, an error message
git://git.exim.org / exim.git / blobdiff