View source

[[Sieve]] is the mail filter scripting language for Cyrus IMAPD (our mail server).  SmartSieve is a web based application which lets you edit Sieve scripts, either directly or through a point and click interface.  SmartSieve, though simple, is fairly powerful and will allow you to create all but the most complex Sieve scripts without ever touching the language itself.


== Getting started ==
Please read over the following sections before starting.


=== Where is it? ===
Point your web browser to https://mail.astro.princeton.edu/smartsieve/ to login.


=== Viewing and editing rules ===
After you login to SmartSieve, you will be brought to your currently active script and the rules in it, if there are any.

A green checkmark next to a rule means that rule is active; conversely, a red X next to a rule means that rule is ignored on incoming mail. To toggle a rule on and off you can click the check to deactivate it, or the X to activate it. To delete a rule entirely, click the trash can icon.

If you want to enable, disable, or delete multiple rules at once, you can select the checkboxes next to the rules you want to act upon, and then click the enable, disable, or delete button at the bottom of the page.

To edit a rule, simply click the text of the rule itself. That will bring you to the "Edit Filter Rule" page, which is the same page you get to add a new rule. Further instruction on editing a rule can be found below.

To change the order of rules, you can use the up and down arrows to the right of the rule you want to move. The up arrow moves the rule up one spot, the down moves it down one. If you want to move it to specific spot more quickly, you can enter the number where it should be moved to in the "To:" box and click either arrow to effect the change.

: Why is the order important?  Because the rules are applied from the first to the last, stopping at the first rule that matches (unless that rule states to continue processing after a match).  This is handy if you wish to divide mails that have similar characteristics.  For example, let's say you have two folders, one for mail from Bob, and one for mail about camping trips.  If you have a rule that puts all mail from Bob into the folder "Bob", and Bob sends you a mail about an upcoming camping trip, that mail will also go into the "Bob" folder.  So, by placing a rule *before* that one that checks for "Camping" in the subject, you can catch mails from Bob that have to do with camping trips, and put them in the camping folder.  Any other mail from Bob will then go to the "Bob" folder.  As a general rule, you want to have the most specific rules at the top of the list, and the least specific rules near the bottom.


=== Adding new rules ===

To add a new sieve rule, click the "New Rule" link at the top of the page.  This will bring up a form with the information required to setup a new filtering rule.

The rule editor works on basic logic. In the 'Conditions' box, set the first box to "If." Select "any of" if you any of the conditions to trigger the action, or select 'all of' if the rule has to match all the conditions. You can think of this as a logical OR or AND.

From the 'Add condition' box you will select the first condition you want to fulfill. Most of these should be obvious in meaning. 'If message header' lets you specify a specific header to match, which is useful if you want to check a header not listed in the drop-down box.

Once you've selected the part of the message you want to check, a drop-down box and input box will appear to the right. The drop-down contains matching operators such as 'contains,' 'does not contain,' 'matches,' 'does not match,' and so on. Select the proper operator for the rule you wish to write. In the input box to the right of that, you can enter a string (or regular expression if you want to build one) that you want to use for the comparison.

Once you've created your first condition, you can add additional conditions below by selecting another condition from the 'Add condition' box. To delete a condition, hit the little trash can icon to the right of the condition.

The next step is to tell sieve exactly what you want to do with the mail which matches the rule. From the 'Add action' drop-down, you can select one of the following:

* file into
*: The drop-down box lets you choose what folder the mail will be filed into
* forward to address
*: Enter an address into the corresponding text box where you wish to have the mail forwarded
* send a reject message
*: You may type a rejection notice which will be sent back to the sender (this will generate a bounce message)
* discard the message
*: Will silently throw the message away.
* send vacation message
*: You can add an automated reply to send back to the sender to the text box here.
* set message flag
*: This can alter message flags, typically used by your mail program to mark a message read, replied to, new, etc.
* keep a copy in your mailbox
*: This does exactly what it says -- keeps a copy of the message in your mailbox. This is useful if you want to forward a message as well as keep a copy locally. 
*: '''NOTE''': '''Please don't do this just to keep backups here!'''  It wastes the resources of the mail server to index and store thousands of messages that will never be read.  If you're forwarding your mail elsewhere, keep the "keep" option off (or perhaps turn it off after you're satisfied your mail is going where it should and then clean up the email left on the server!)
* Stop processing filter rules
*: This also is fairly self-explanatory. It will cause sieve to completely stop processing '''all''' filter rules at this point.

The final rule setting is telling SmartSieve exactly where the rule should be in order. By default, it will make it the last rule, but if you want it earlier, you can select a different position from the 'Save at position' option.

Once your rule is configured the way you want, hit the 'Save Rule' button at the bottom of the page.


=== Whitelists ===

SmartSieve makes it easy to whitelist addresses. Whitelisted addresses will bypass any filtering rules you have defined for your e-mail, including any which move suspected spam mail into your spam folder.

# Login to SmartSieve as instructed above
# Click the '''Whitelist''' option at the top of the page.
# On the next page, enter an address which you want to whitelist. 
# If you want to enter additional e-mail addresses, hit '''New Address''' or hit '''Save Changes''' if you're finished. 

If you then click '''Filter Rules''' at the top of the page to get back to your main rules listing, you'll see SmartSieve inserted a new rule at the top of the ruleset to stop processing if the from header matches the address(es) you've whitelisted.


=== Forwarding mail to another account ===

It's very easy to forward your mail to another account.

# Login to SmartSieve as instructed above
# Click '''Forward Mail''' at the top of the page.
# On the next page, enter the destination address in the '''Forward to address''' field.
#: If you want to also keep a copy of all forwarded mail on the Astro servers, check the '''Keep a copy in your Inbox''' box.
#: '''NOTE''': '''Please don't do this just to keep backups here!'''  It wastes the resources of the mail server to index and store thousands of messages that will never be read.  If you're forwarding your mail elsewhere, keep the "keep" option off (or perhaps turn it off after you're satisfied your mail is going where it should and then clean up the email left on the server!)
# Hit '''Save Changes'''

If your Sieve script wasn't active before, it will be automatically activated. Forwarding should now be active. We suggest sending a test message from another account just to make sure the forwarding is working as expected.


==== Disabling forwarding ====

If you would like to disable forwarding your mail elsewhere, go into the Mail Forwarding screen as above, and hit the '''Delete''' button. This will ask you to confirm that you want to delete the rule. Click '''OK''' to confirm.


=== Vacation Messages ===

If you want to create a temporary "out of office" auto-reply message, do the following:

# Login to SmartSieve as instructed above
# Click '''Vacation Messages''' at the top of the page
# Edit the form to suit your needs
#: '''Message''' is the field for the message you want sent as a reply to e-mails received while it's active
#: '''Days between responses''' is how often a single e-mail address will actually be sent a reply while the vacation message is active. So, if someone e-mails you often, they'll only get an automated reply once every X days (where X is the value you selected), rather than every single time they send you an e-mail.
#: '''Your e-mail addresses''' These are the addresses that mail is sent to that you wish to reply to. In just about all cases, you want to check the box for your e-mail address and leave the box below that blank. This option is here if you have multiple e-mail accounts directed to your Astro address and only want to auto-reply to one or some of them.
# Once you're done, hit '''Save Changes'''


To disable a vacation message, go back in as above, and from the '''Vacation Messages''' screen, hit the '''Delete''' button. Hit '''OK''' to confirm that you want to delete the vacation message.


=== Filtering Spam ===

All incoming messages to Astro e-mail addresses are automatically scanned for spam and virus content. By default, those messages which have a very high spam score are automatically rejected, so you'll never see them. Messages which score a medium spam score are tagged as spam, but then sent along to your Inbox. Quite often, these messages are indeed spam, and you might want to have them sent to a dedicated Junk Mail folder. To accomplish this, do the following:

# The first thing you need to do is create a folder on the server to hold the spam messages. You can do this in most GUI mail clients by right-clicking on your Inbox folder, and selecting New Folder or New Mailbox. Call the mailbox whatever you wish. Spam or Junk is typical.
# Once you have your folder, login to SmartSieve as instructed above.
# Click '''Filter Spam'''
# From the '''Add Action''' drop-down menu, select '''File Into'''
# From the drop-down menu which appears to the right of that, select '''INBOX.spam''' (or '''INBOX.whatever''' you named your junk folder).
# Unless you want to do anything else with the spam (as described in a section above), hit '''Save Changes'''. This will make the spam rule the highest priority.

From this point forward, anything that the server marks as being possible spam, will get redirected into your selected spam folder. You will want to check this folder every so often to make sure any legitimate mail wasn't caught, and to empty it so it doesn't waste space on the server.


[[Category:Email]]