rfc3028.txt

RFC3028:Sieve: A Mail Filtering Language

   Implementations SHOULD support "reject" and "fileinto".





Showalter                   Standards Track                    [Page 19]

RFC 3028            Sieve: A Mail Filtering Language        January 2001


   Implementations MAY limit the number of certain actions taken (see
   section 2.10.4).

4.1.     Action reject

   Syntax:   reject <reason: string>

   The optional "reject" action refuses delivery of a message by sending
   back an [MDN] to the sender.  It resends the message to the sender,
   wrapping it in a "reject" form, noting that it was rejected by the
   recipient.  In the following script, message A is rejected and
   returned to the sender.

   Example:  if header :contains "from" "[e-mail]" {
                reject "I am not taking mail from you, and I don't want
                your birdseed, either!";
             }

   A reject message MUST take the form of a failure MDN as specified  by
   [MDN].    The  human-readable  portion  of  the  message,  the  first
   component of the MDN, contains the human readable message  describing
   the  error,  and  it  SHOULD  contain  additional  text  alerting the
   original sender that mail was refused by a filter.  This part of  the
   MDN might appear as follows:

   ------------------------------------------------------------
   Message was refused by recipient's mail filtering program.  Reason
   given was as follows:

   I am not taking mail from you, and I don't want your birdseed,
   either!
   ------------------------------------------------------------

   The MDN action-value field as defined in the MDN specification MUST
   be "deleted" and MUST have the MDN-sent-automatically and automatic-
   action modes set.

   Because some implementations can not or will not implement the reject
   command, it is optional.  The capability string to be used with the
   require command is "reject".

4.2.     Action fileinto

   Syntax:   fileinto <folder: string>

   The "fileinto" action delivers the message into the specified folder.
   Implementations SHOULD support fileinto, but in some environments
   this may be impossible.



Showalter                   Standards Track                    [Page 20]

RFC 3028            Sieve: A Mail Filtering Language        January 2001


   The capability string for use with the require command is "fileinto".

   In the following script, message A is filed into folder
   "INBOX.harassment".

   Example:  require "fileinto";
             if header :contains ["from"] "coyote" {
                fileinto "INBOX.harassment";
             }

4.3.     Action redirect

   Syntax:   redirect <address: string>

   The "redirect" action is used to send the message to another user at
   a supplied address, as a mail forwarding feature does.  The
   "redirect" action makes no changes to the message body or existing
   headers, but it may add new headers.  The "redirect" modifies the
   envelope recipient.

   The redirect command performs an MTA-style "forward"--that is, what
   you get from a .forward file using sendmail under UNIX.  The address
   on the SMTP envelope is replaced with the one on the redirect command
   and the message is sent back out.  (This is not an MUA-style forward,
   which creates a new message with a different sender and message ID,
   wrapping the old message in a new one.)

   A simple script can be used for redirecting all mail:

   Example:  redirect "[e-mail]";

   Implementations SHOULD take measures to implement loop control,
   possibly including adding headers to the message or counting received
   headers.  If an implementation detects a loop, it causes an error.

4.4.     Action keep

   Syntax:   keep

   The "keep" action is whatever action is taken in lieu of all other
   actions, if no filtering happens at all; generally, this simply means
   to file the message into the user's main mailbox.  This command
   provides a way to execute this action without needing to know the
   name of the user's main mailbox, providing a way to call it without
   needing to understand the user's setup, or the underlying mail
   system.





Showalter                   Standards Track                    [Page 21]

RFC 3028            Sieve: A Mail Filtering Language        January 2001


   For instance, in an implementation where the IMAP server is running
   scripts on behalf of the user at time of delivery, a keep command is
   equivalent to a fileinto "INBOX".

   Example:  if size :under 1M { keep; } else { discard; }

   Note that the above script is identical to the one below.

   Example:  if not size :under 1M { discard; }

4.5.     Action discard

   Syntax:   discard

   Discard is used to silently throw away the message.  It does so by
   simply canceling the implicit keep.  If discard is used with other
   actions, the other actions still happen.  Discard is compatible with
   all other actions.  (For instance fileinto+discard is equivalent to
   fileinto.)

   Discard MUST be silent; that is, it MUST NOT return a non-delivery
   notification of any kind ([DSN], [MDN], or otherwise).

   In the following script, any mail from "[e-mail]" is thrown
   out.

   Example:  if header :contains ["from"] ["[e-mail]"] {
                discard;
             }

   While an important part of this language, "discard" has the potential
   to create serious problems for users: Students who leave themselves
   logged in to an unattended machine in a public computer lab may find
   their script changed to just "discard".  In order to protect users in
   this situation (along with similar situations), implementations MAY
   keep messages destroyed by a script for an indefinite period, and MAY
   disallow scripts that throw out all mail.

5.      Test Commands

   Tests are used in conditionals to decide which part(s) of the
   conditional to execute.

   Implementations MUST support these tests: "address", "allof",
   "anyof", "exists", "false", "header", "not", "size", and "true".

   Implementations SHOULD support the "envelope" test.




Showalter                   Standards Track                    [Page 22]

RFC 3028            Sieve: A Mail Filtering Language        January 2001


5.1.     Test address

   Syntax:   address [ADDRESS-PART] [COMPARATOR] [MATCH-TYPE]
             <header-list: string-list> <key-list: string-list>

   The address test matches Internet addresses in structured headers
   that contain addresses.  It returns true if any header contains any
   key in the specified part of the address, as modified by the
   comparator and the match keyword.

   Like envelope and header, this test returns true if any combination
   of the header-list and key-list arguments match.

   Internet email addresses [IMAIL] have the somewhat awkward
   characteristic that the local-part to the left of the at-sign is
   considered case sensitive, and the domain-part to the right of the
   at-sign is case insensitive.  The "address" command does not deal
   with this itself, but provides the ADDRESS-PART argument for allowing
   users to deal with it.

   The address primitive never acts on the phrase part of an email
   address, nor on comments within that address.  It also never acts on
   group names, although it does act on the addresses within the group
   construct.

   Implementations MUST restrict the address test to headers that
   contain addresses, but MUST include at least From, To, Cc, Bcc,
   Sender, Resent-From, Resent-To, and SHOULD include any other header
   that utilizes an "address-list" structured header body.

   Example:  if address :is :all "from" "[e-mail]" {
                discard;

5.2.     Test allof

   Syntax:   allof <tests: test-list>

   The allof test performs a logical AND on the tests supplied to it.

   Example:  allof (false, false)  =>   false
             allof (false, true)   =>   false
             allof (true,  true)   =>   true

   The allof test takes as its argument a test-list.







Showalter                   Standards Track                    [Page 23]

RFC 3028            Sieve: A Mail Filtering Language        January 2001


5.3.     Test anyof

   Syntax:   anyof <tests: test-list>

   The anyof test performs a logical OR on the tests supplied to it.

   Example:  anyof (false, false)  =>   false
             anyof (false, true)   =>   true
             anyof (true,  true)   =>   true

5.4.     Test envelope

   Syntax:   envelope [COMPARATOR] [ADDRESS-PART] [MATCH-TYPE]
             <envelope-part: string-list> <key-list: string-list>

   The "envelope" test is true if the specified part of the SMTP (or
   equivalent) envelope matches the specified key.

   If one of the envelope-part strings is (case insensitive) "from",
   then matching occurs against the FROM address used in the SMTP MAIL
   command.

   If one of the envelope-part strings is (case insensitive) "to", then
   matching occurs against the TO address used in the SMTP RCPT command
   that resulted in this message getting delivered to this user.  Note
   that only the most recent TO is available, and only the one relevant
   to this user.

   The envelope-part is a string list and may contain more than one
   parameter, in which case all of the strings specified in the key-list
   are matched against all parts given in the envelope-part list.

   Like address and header, this test returns true if any combination of
   the envelope-part and key-list arguments is true.

   All tests against envelopes MUST drop source routes.

   If the SMTP transaction involved several RCPT commands, only the data
   from the RCPT command that caused delivery to this user is available
   in the "to" part of the envelope.

   If a protocol other than SMTP is used for message transport,
   implementations are expected to adapt this command appropriately.

   The envelope command is optional.  Implementations SHOULD support it,
   but the necessary information may not be available in all cases.





Showalter                   Standards Track                    [Page 24]

RFC 3028            Sieve: A Mail Filtering Language        January 2001


   Example:  require "envelope";
             if envelope :all :is "from" "[e-mail]" {
                discard;
             }

5.5.     Test exists

   Syntax:   exists <header-names: string-list>

   The "exists" test is true if the headers listed in the header-names
   argument exist within the message.  All of the headers must exist or
   the test is false.

   The following example throws out mail that doesn't have a From header
   and a Date header.

   Example:  if not exists ["From","Date"] {
                discard;
             }

5.6.     Test false

   Syntax:   false

   The "false" test always evaluates to false.

5.7.     Test header

   Syntax:   header [COMPARATOR] [MATCH-TYPE]
             <header-names: string-list> <key-list: string-list>

   The "header" test evaluates to true if any header name matches any
   key.  The type of match is specified by the optional match argument,
   which defaults to ":is" if not specified, as specified in section
   2.6.

   Like address and envelope, this test returns true if any combination
   of the string-list and key-list arguments match.

   If a header listed in the header-names argument exists, it contains
   the null key ("").  However, if the named header is not present, it
   does not contain the null key.  So if a message contained the header

           X-Caffeine: C8H10N4O2







Showalter                   Standards Track                    [Page 25]

RFC 3028            Sieve: A Mail Filtering Language        January 2001


   these tests on that header evaluate as follows:

           header :is ["X-Caffeine"] [""]         => false
           header :contains ["X-Caffeine"] [""]   => true

5.8.     Test not