Computing Facilities    links to the SCS and CMU home pages Carnegie Mellon School of Computer Science Carnegie Mellon University
 
Advanced search tips 
 Documentation
 » Introduction to Facilities 
 » Accounts & passwords 
 » AFS 
 » Application software 
 » AV help 
 » Backups & restores 
 » Calendaring 
 » E-mail 
 » Networking 
 » Printing 
 » Purchasing 
 » Resource management 
 » Security 
 » Software licensing 
 » Support charges 
 » Web publishing 
 » Your health 
 » Mac support 
 » Linux support 
 » Windows PC support 

Sieve in the SCS Environment

Sieve, one of several Corvid mechanisms for filtering email, is a server-side mail-processing system built into the Cyrus IMAP server.

Intended to be simple, Sieve only processes mail at delivery time — mail delivered to the IMAP server will only pass through Sieve once. Sieve's command set is somewhat limited, in an attempt to reduce the possibility of mail loops (or similiar effects of "clever" behavior). While simple, Sieve is sufficiently powerful deal with most common tasks involving incoming mail at delivery time.

What Sieve Can Do

Based on an email message's specific characteristics, Sieve can perform numerous operations. Common tasks include:

  • Automatically file the mail into a folder (or folders)
  • Forward a copy to another address
  • Send notification of arrival (via zephyr)
  • Statically whitelist or blacklist domains and addresses

In addition, Sieve can send automatic vacation-messages.

For a more comprehensive tour of Sieve functionality, see Writing Custom Scripts, below.

What Sieve Does Not Do

Because of the environment Sieve runs in and the desire to keep Sieve simple, some limitations obtain:
  • Sieve can not call out to arbitrary external programs
  • Sieve processes mail only once, upon delivery

While Sieve does not offer these capabilities, the Corvid mail system still does. See the page on Corvid external processing for details.

Simple Spam-filtering and Vacation-message Setup

Since the most common operations involve filtering spam and setting up vacation messages, Sieve provides the Websieve script editor, which can quickly generate and control appropriate scripts for these purposes.

Note: The simple editor interface generates a new script each time it runs — it does not preserve state and does not remember previous settings. For more permanent solutions, use either the advanced editor or sieveshell, as below.

Customized Sieve Scripting

While the script editor facilitates common tasks, customized Sieve scripts can exploit Sieve's full power. These simple text files reside on the IMAP server, and each user has a protected space for scripts. Users can maintain several Sieve scripts on the server, but only one can be active at a time.

There are currently two supported methods for managing scripts: a Websieve interface and a command-line one.

Custom scripts with the Websieve interface
The "Advanced Use" section of the Websieve interface allows listing scripts on the server, inspecting scripts, adding and removing scripts, editing scripts in place, and selecting the active script. The tool also checks script syntax and will prevent installing a broken script. To use this tool, select the "Advanced Mail Filtering" link from the front page of the Websieve interface. (will open in a new browser window)

The "Advanced Mail Filtering" page includes tools to list scripts on the server, activate and deactivate scripts, inspect individual scripts and edit them in place. The tool checks all edited scripts for syntax and will prevent installing a broken script.

Note: the Websieve tool does not activate scripts by default — processing will only occur if a script is activated. The currently enabled script can be determined by checking which script is designated as (ENABLED) in the list of scripts. If no script is so designated, no processing will take place, and all mail will be delivered to the default location (INBOX).

Custom scripts with sieveshell
The sieveshell Unix command-line tool, available in the SCS computing environment as part of the Corvid system:
  bovik$ sieveshell imap.srv.cs.cmu.edu

sieveshell can list scripts on the server, inspect scripts, add and remove scripts from the server, and select the active script. The tool will check all new scripts for syntax and will prevent installing a broken script.

The help command will show a list of available commands, with a brief description for each. The following commands are available:

  • help — display the help screen
  • list — list available scripts on the server
  • put <filename> — upload filename to the server
  • get <scriptname> [<filename>] — Display scriptname (if a filename is given, save the script to that file)
  • delete <scriptname> — delete the script scriptname
  • activate <scriptname> — set scriptname as the active script
  • deactivate — deactivate all scripts
  • quit — quit the sieveshell utility

Note: sieveshell does not activate scripts by default — processing will only occur if a script is activated. The currently enabled script can be determined by checking which script is designated as the active script in the list of scripts. If no script is so designated, no processing will take place, and all mail will be delivered to the default location (INBOX).

Writing Custom Scripts

A Sieve Cookbook — General notes
The Sieve processing system uses a scripting language to process mail. While each user may keep multiple scripts on the server, only one can be active at one time. Sieve scripts execute in order and will generally try to continue processing mail until told to stop (either implictly by using a command like fileinto, or explicitly). The default action delivers mail into the user's INBOX.

While we recommend keeping scripts as simple as possible, Sieve can be a powerful tool! Please exercise care when writing and testing Sieve scripts; it is possible to lose mail irretrievably with a badly formed script.

Sieve-script syntax is important; both the Websieve interface and sieveshell will check your syntax for you and prevent installing broken scripts.

Comments
Any line starting with a "#" is treated as a comment. This feature provides a useful means to document what a script does, especially if the script gets "clever."
The require line
All Sieve scripts must begin with a require statement, which defines what extensions the Sieve subsystem can use to process mail. In most cases, this line should include all available extensions, for example:

require["fileinto","reject","vacation","imapflags","relational","regex","notify"];

There should only be one require line in a Sieve script.

Selecting messages
In if blocks, the selection criteria for messages can be specified either singly:
  if header :contains "From" "bovik@cs.cmu.edu" {...}

... or in a list:

  if header :contains "From" ["bovik@cs.cmu.edu","bovik+@cs.cmu.edu","hbovik@gmail.com"] {...}

In the first example, the Sieve script will act on mail from "bovik@cs.cmu.edu." In the second example, the script will act on mail from any of the addresses specified.

Filing mail into a folder
Sieve files mail into specific folders with the fileinto command. In the following example, mail from "bovik@cs.cmu.edu" is automatically filed into the Bovik mailbox:
  # Check whether the message is from a specific user
  #
  if header :contains "From" "bovik@cs.cmu.edu" {
      fileinto "INBOX.Bovik";
  }

Note: please make sure when using the fileinto command that the folder specified exists!

Sieve can also check other headers. For example, checking the "To" field can be handy for dealing with mailing lists:

  # Put mail from the SCS-all mailing list into a folder:
  #
  if header :contains "To" "scs-all@cs.cmu.edu" {
      fileinto "INBOX.scsall";
  }

Or, as another example, Sieve can handle automatic filing of things like the PMX:VIRUS messages:

  # Put virus warnings into their own folder
  #
  if header :contains "Subject" "PMX:VIRUS" {
      fileinto "INBOX.VIRUS";
  }
Filtering spam
Filtering spam is a lot like the above example, except this time the test is for a special header added by the PureMessage spam tagging service.
  # Check whether PureMessage considers this message to be spam;
  # if so, file it into the SPAM folder
  #
  if header :contains "X-Spam-Warning" "" {
      fileinto "INBOX.SPAM";
  }

Note: the "SPAM" folder is created by default with each IMAP account.

Redirecting or Resending Mail
Redirecting mail can be accomplished with the redirect command. This can be useful if the user would also like to receive mail at another address:
  # Resend a copy of the message to another address
  #
  if true {
      redirect "bovik@exchange.cs.cmu.edu";
  }
Vacation Messages
Sieve can handle the automatic sending of vacation messages:
  # Automatic vacation message
  #
  vacation 
      :days 3 
      :addresses ["bovik+@cs.cmu.edu","harry.bovik@cs.cmu.edu"] 
      :subject "Vacation Message"

  # Body of the vacation message, in double quotes
  "
  Sorry, you missed me. I'm currently on a speaking tour 
  and will read your e-mail on my return.
  "
  ;

There are several options in the above script that the user can set:

The :days keyword will set the notification timeout for sending vacation messages. Sieve keeps track of who has received vacation notification messages from a user, and can hold off on sending responses even if the sender continues to send mail. In the above example, Sieve will wait three days between sending automatic notifications. Note: this should not be used to specify the length of a vacation; turning off vacation messages is accomplished by activating another script.

The :addresses keyword is used to list mail addresses that require an automatic apply. The vacation extension works on strict matches, so if the user has multiple email addresses, they should be listed here.

The :subject keyword specifies the Subject line of the automatic response mail.

The remainder of vacation stanza is the body of the automatic response mail, enclosed in double quotes and terminated with a semicolon.

Sieve Script Examples - Putting it all together

Our good Professor Bovik wants to set up two scripts: a general-purpose one that does typical filtering duties and a travelling version that he can use on the road.
A general-purpose script
  # Harry's general-purpose Sieve script
  #
  # general.sieve
  #
  require ["fileinto","reject","vacation","imapflags","relational","regex","notify"];

  # Move mail tagged as SPAM into a dedicated folder
  if header :matches "X-Spam-Warning" "*" {
      fileinto "INBOX.SPAM";
  }
  # Move PMX:VIRUS messages into a dedicated folder
  elsif header :contains "Subject" "PMX:VIRUS" {
      fileinto "INBOX.VIRUS";
  }
  # Process everything else...
  else {
      # Send a copy to the exchange server as a backup
      redirect "bovik@exchange.cs.cmu.edu";

      # File mail to scs-all into a dedicated folder
      if header :contains "To" "scs-all@cs.cmu.edu" {
          fileinto "INBOX.scsall";
      }
      # Deliver everything else to INBOX
      else {
          fileinto "INBOX";
      }
  }
A travelling script
  # Harry's travelling Sieve script
  #
  # general.sieve
  #
  require ["fileinto","reject","vacation","imapflags","relational","regex","notify"];

  # Move mail tagged as SPAM into a dedicated folder
  if header :matches "X-Spam-Warning" "*" {
      fileinto "INBOX.SPAM";
  }
  # Move PMX:VIRUS messages into a dedicated folder
  elsif header :contains "Subject" "PMX:VIRUS" {
      fileinto "INBOX.VIRUS";
  }
  # Process everything else...
  else {
      # Send a copy to the exchange server as a backup
      redirect "bovik@exchange.cs.cmu.edu";

      # Send a copy to the travelling account, too
      redirect "hbovik@gmail.com";

      # File mail to scs-all into a dedicated folder
      if header :contains "To" "scs-all@cs.cmu.edu" {
          fileinto "INBOX.scsall";
      }
      # Deliver everything else to INBOX
      else {
          fileinto "INBOX";
      }
  }

  vacation 
      :days 3 
      :addresses ["bovik+@cs.cmu.edu","harry.bovik@cs.cmu.edu"] 
      :subject "Vacation Message"

  # Body of the vacation message, in double quotes
  "
  Sorry, you missed me. I'm currently on a speaking tour 
  and will read your e-mail on my return.
  "
  ;

With both scripts on the server, Harry can simply select the vacation script when he leaves town and reactivate the general script on returning.