Menu
▾
▴
[GS-VCS] SF.net SVN: gatorsieve: [122] WebSieve/trunk
|
From: <lg...@us...> - 2006-04-21 18:44:31
|
Revision: 122 Author: lgzzsf Date: 2006-04-21 11:44:24 -0700 (Fri, 21 Apr 2006) ViewCVS: http://svn.sourceforge.net/gatorsieve/?rev=122&view=rev Log Message: ----------- More changes to help.html Modified Paths: -------------- WebSieve/trunk/src/webapp/help.html Added Paths: ----------- WebSieve/trunk/ToDo.txt Added: WebSieve/trunk/ToDo.txt =================================================================== --- WebSieve/trunk/ToDo.txt (rev 0) +++ WebSieve/trunk/ToDo.txt 2006-04-21 18:44:24 UTC (rev 122) @@ -0,0 +1,8 @@ +1. Tip of the page view: create a footer help message to encourage people to use features. +2. Add a tooltip describing commands and features implemented by capabilities +3. Client side syntax validation +4. Cross reference help to create scripts +5. General improve quick help +6. Wizard to create scripts +7. "Automator" interface +8. Add validation for folders, either by creating new folder or making sure it exists \ No newline at end of file Modified: WebSieve/trunk/src/webapp/help.html =================================================================== --- WebSieve/trunk/src/webapp/help.html 2006-04-20 17:58:44 UTC (rev 121) +++ WebSieve/trunk/src/webapp/help.html 2006-04-21 18:44:24 UTC (rev 122) @@ -5,19 +5,268 @@ <div id="Introduction" class="section" title="Introduction"> <p> - Sieve is a language for filtering e-mail messages at the time - of final delivery. It is designed to be implementable on either a - mail client or mail server. It has no variables, loops, nor the - ability to shell out to external programs. - Sieve scripts are just a series of instructions written in plain text which tell - the Sieve engine what to do with your incoming email. Although designed to - be simple to use Sieve scripting is a programming language so to gain effective - use of it familiarity with basic programming code and concepts is required. - Those who attempt to develop and use a Sieve script from scratch, - should be familiar with basic scripting and with Sieve specifically. + Sieve is a language that can be used to create filters for email. + This filtering is done at the time of final delivery to the INBOX. + Using message headers and matching rules, Sieve scripts can do the following: + <ul> + <li>discard email</li> + <li>bounce email back to the sender with a rejection notice</li> + <li>redirect the message to another address</li> + <li>file mail into a specific folder in the INBOX</li> + </ul> + Sieve scripts are just a series of instructions written in plain text which tell the Sieve + engine what to do with your incoming email. Although designed to be simple to use, + it is helpful to understand basic programming concepts. Don't despair. + This document provides plenty of examples to help users at all levels of understanding write a Sieve script. </p> </div> +<div id="DevelopingScripts" class="section" title="Developing sieve scripts"> +<p> + To create Sieve scripts you should be familiar with scripting and sieve commands. + This section includes the list of commands currently supported by the UF mail server and examples on how to use them. Sieve scripts are an advanced feature that may affect POP users negatively. + You can use multiple Sieve scripts that use several different capabilities so that only e-mail that passes each of the Sieve script criteria would appear in your INBOX. Only one Sieve script can be active at a time; however, you can have more than one script uploaded to the server. A script can include more than one command, which is useful to narrow down the amount of email that arrives in your INBOX. +</p> + +<div id="Capabilities" class="section" title="Capabilities"> +<ul> +<li> fileinto + <p> + + The "fileinto" action delivers the message into the specified folder. + </p> + <p> + Example 1: In this example, before you enable the script, create a "harassment" folder under your INBOX. All e-mail that meets the + criteria will be deposited into the "harassment" folder. + <pre><code>require "fileinto"; + if header :contains ["from"] "coyote" { + fileinto "INBOX.harassment";} + }</code></pre> + + </p> + <p>Example 2: This Sieve script will reject e-mail where the "To" field does not include your name or e-mail address. + Typically, this type of mail is spam. Before you enable the script, create a junk mail folder under your INBOX. + <pre><code>require "fileinto"; + if anyof ( not address :all :contains ["To", "Cc", "Bcc"] "you...@yo..." ) { + fileinto "INBOX.Junk";} + </code></pre> + </p> + + <p> + Example 3: This Sieve script will copy all e-mail sent through a ".da.uu.net" server into a junk folder. The script is effective even if mail is relayed + through an international open mail relay. Before you enable the script, create a junk mail folder under your INBOX. + <pre><code>require "fileinto"; + if header :contains "Received" ".da.uu.net" { + fileinto "INBOX.Junk";} + </code></pre> + </p> + +</li> + +<li> reject + <p> + The reject" action refuses delivery of a message by resending + 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. + </p> + + <p>Example 1: This Sieve script will reject junk e-mail where the "To" field includes "bigfoot.com". + Typically, mail address to "bigfoot" is spam. + <pre><code>if header :contains "To" "@bigfoot.com" { + reject "Please remove my name from your mailing list";} + </code></pre> + </p> + <p>Example 2: This Sieve script will reject junk e-mail where the "From" field includes "bigfoot.com". + + <pre><code>if header :contains "from" "bigfoot.com" { + reject "I am not taking mail from you";} + }</code></pre> + </p> +</li> + +<li> subaddress + <p>On email systems that allow for "subaddressing" or "detailed + addressing" (e.g., "ken...@ex..."), it is sometimes + desirable to make comparisons against these sub-parts of addresses. + </p> + + Example: + <pre><code>require "subaddress"; + + # File mailing list messages (subscribed as "ken+mta-filters"). + if envelope :detail "to" "mta-filters" { + fileinto "inbox.ietf-mta-filters"; + } + + # If a message is not to me (ignoring +detail), junk it. + if not allof (address :user ["to", "cc", "bcc"] "ken", address :domain ["to", "cc", "bcc"] "example.org") { + discard; + }</code></pre> +</li> + +<li> envelope + <p> + In most cases, the envelope "to" address is the preferred + address to examine for subaddress information when the desire is to + sort messages based on how they were addressed so as to get to a + specific recipient. The envelope address is, after all, the reason a + given message is being processed by a given sieve script for a given + user. This is particularly true when mailing lists, aliases, and + "virtual domains" are involved since the envelope may be the only + source of detail information for the specific recipient. + </p> + Example: + <pre><code>require "envelope"; + if envelope :all :is "from" "ti...@ex..." { + discard; + # Redirect all mail sent to +foo. + if envelope :detail "to" "foo" { + redirect "ke...@ex..."; + } + }</code></pre> + +</li> + +<li> vacation + <p> + The "vacation" action implements a vacation autoresponder with the + purpose to provide correspondents with notification that the user + is away for an extended period of time and that they should not + expect quick responses. + </p> + + <p>Example: + <pre><code>require "vacation"; + if header :contains "subject" "cyrus" { + vacation "I'm out -- send mail to cyrus-bugs"; + } else { + vacation "I'm out -- call me at +1 304 555 0123"; + }</code></pre> + </p> + +</li> + +<li> imapflags + <p>This is an extension for setting [IMAP] flags. It defines several new actions "setflag", + "addflag", "removeflag", "mark" and "unmark". + + </p> + Example: + <pre><code>if header :contains "from" "bo...@fr..." { + setflag "\\Flagged"; + fileinto "INBOX.From Boss"; + }</code></pre> +</li> + +<li> notify + <p>The Notify action specifies that a notification should be sent to the + user. </p> + + Example: + <pre><code>require ["notify", "fileinto", "variables"]; + + if header :contains "from" "bo...@ex..." { + notify :priority "1" :message "This is probably very important"; + # Don't send any further notifications + stop; + } + if header :contains "to" "sie...@ex..." { + # :matches is used to get the value of the Subject header + if header :matches "Subject" "*" { + set "subject" "${1}"; + } + + # :matches is used to get the value of the From header + if header :matches "From" "*" { + set "from" "${1}"; + } + + notify :priority "3" :message "[SIEVE] ${from}: ${subject}"; + fileinto "INBOX.sieve"; + }</code></pre> +</li> + + +<li> relational + <p> + The RELATIONAL extension provides relational operators on the + address, envelope, and header tests. This extension also provides a + way of counting the entities in a message header or address field. + </p> + Example: + + <pre><code>require ["relational", "comparator-i;ascii-numeric"]; + + if header :value "lt" :comparator "i;ascii-numeric" ["x-priority"] ["3"] { + fileinto "Priority"; + } elseif address :count "gt" :comparator "i;ascii-numeric" ["to"] ["5"] { + # everything with more than 5 recipients in the "to" field + # is considered SPAM + fileinto "SPAM"; + } elseif address :value "gt" :all :comparator "i;ascii-casemap" ["from"] ["M"] { + fileinto "From N-Z"; + } else { + fileinto "From A-M"; + } + + if allof ( address :count "eq" :comparator "i;ascii-numeric" ["to", "cc"] ["1"] , address :all :comparator "i;ascii-casemap" ["to", "cc"] ["me...@fo...valid"] { + fileinto "Only me"; + }</code></pre> +</li> + +<li> comparator-i;ascii-numeric + <p> + + The numeric value can be compared to specific values using the SIEVE relational + extension in conjunction with the "i;ascii-numeric" + comparator, which will test for the presence of a numeric + value at the start of the string, ignoring any additional text in the + string. The additional text can be used to carry implementation + specific details about the tests performed and descriptive comments + about the result. + The "i;ascii-numeric" comparator, MUST be + supported for any implementation of this extension. The comparator + "i;ascii-numeric" MUST support at least 32 bit unsigned integers. + </p> + Example: + <pre><code>require ["spamtest", "fileinto", "relational", "comparator-i;ascii-numeric"]; + + if spamtest :value "eq" :comparator "i;ascii-numeric" "0" { + fileinto "INBOX.unclassified"; + } elsif spamtest :value "ge" :comparator "i;ascii-numeric" "3" { + fileinto "INBOX.spam-trap"; + }</code></pre> + +</li> + +<li> regex + <p> + Commands that support matching may take the optional tagged argument + ":regex" to specify that a regular expression match should be + performed. The ":regex" match type is compatible with both the "i;octet" and + "i;ascii-casemap" comparators and may be used with them. + </p> + + Example: + <pre><code>require "regex"; + # Try to catch unsolicited email. + if anyof ( + # if a message is not to me (with optional +detail), + not address :regex ["to", "cc", "bcc"] "me(\\\\+.*)?@company\\\\.com", + + # or the subject is all uppercase (no lowercase) + header :regex :comparator "i;octet" "subject" "^[^[:lower:]]+$" + ) { + discard; # junk it + }</code></pre> +</li> + +</ul> +</div> + +</div> + <div id="InstallingScript" class="section" title="Installing a script"> <p> There are two ways to install a script, creating a new script from scratch and upload an existing script. @@ -25,6 +274,7 @@ <div id="CreatingScript" class="section" title="Creating a new script"> <p> + You can edit a script's contents in the text area. To install a new script, go to <a href="edit">Creating Sieve Scripts</a> and to the Create a new sieve script, type in the box area the script you want to create. @@ -34,11 +284,13 @@ <div id="UploadingScript" class="section" title="Uploading an existing script"> <p> + You can upload a script from your hard drive, go to <a href="edit">Creating Sieve Scripts</a> and to the Upload a local sieve script, click on browse to look for a file in the file system that you want to upload. Choose a file name to be uploaded and press the upload button. </p> + </div> <div id="CopyingScript" class="section" title="Copying a script"> @@ -47,6 +299,7 @@ and saving the script name with a different name. Choose a script name and press the save button. </p> + </div> </div> @@ -55,206 +308,12 @@ <!--</div>--> -<div id="Capabilities" class="section" title="Capabilities"> - <ul> - <li> fileinto - <p> - The "fileinto" action delivers the message into the specified folder. - </p> - Example: -<pre><code>require "fileinto"; -if header :contains ["from"] "coyote" { - fileinto "INBOX.harassment"; -}</code></pre> - </li> - <li> reject - <p> - The reject" action refuses delivery of a message by resending - 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. - </p> - Example: -<pre><code> if header :contains "from" "co...@de..." { - reject "I am not taking mail from you"; -}</code></pre> - </li> - <li> envelope - <p> - In most cases, the envelope "to" address is the preferred - address to examine for subaddress information when the desire is to - sort messages based on how they were addressed so as to get to a - specific recipient. The envelope address is, after all, the reason a - given message is being processed by a given sieve script for a given - user. This is particularly true when mailing lists, aliases, and - "virtual domains" are involved since the envelope may be the only - source of detail information for the specific recipient. - </p> - Example: -<pre><code>require "envelope"; -if envelope :all :is "from" "ti...@ex..." { - discard; - # Redirect all mail sent to +foo. - if envelope :detail "to" "foo" { - redirect "ke...@ex..."; - } -}</code></pre> - </li> - - <li> vacation - <p> - The "vacation" action implements a vacation autoresponder with the - purpose to provide correspondents with notification that the user - is away for an extended period of time and that they should not - expect quick responses. - </p> - - <p>Example: -<pre><code>require "vacation"; -if header :contains "subject" "cyrus" { - vacation "I'm out -- send mail to cyrus-bugs"; -} else { - vacation "I'm out -- call me at +1 304 555 0123"; -}</code></pre> - </p> - </li> - - <li> imapflags - <p>This is an extension for setting [IMAP] flags. It defines several new actions "setflag", - "addflag", "removeflag", "mark" and "unmark". - - </p> - Example: -<pre><code>if header :contains "from" "bo...@fr..." { - setflag "\\Flagged"; - fileinto "INBOX.From Boss"; -}</code></pre> - </li> - - <li> notify - <p>The Notify action specifies that a notification should be sent to the - user. </p> - Example: -<pre><code>require ["notify", "fileinto", "variables"]; - -if header :contains "from" "bo...@ex..." { - notify :priority "1" :message "This is probably very important"; - # Don't send any further notifications - stop; -} -if header :contains "to" "sie...@ex..." { - # :matches is used to get the value of the Subject header - if header :matches "Subject" "*" { - set "subject" "${1}"; - } - - # :matches is used to get the value of the From header - if header :matches "From" "*" { - set "from" "${1}"; - } - - notify :priority "3" :message "[SIEVE] ${from}: ${subject}"; - fileinto "INBOX.sieve"; -}</code></pre> - </li> - - <li> subaddress - <p>On email systems that allow for "subaddressing" or "detailed - addressing" (e.g., "ken...@ex..."), it is sometimes - desirable to make comparisons against these sub-parts of addresses. - </p> - Example: -<pre><code>require "subaddress"; - -# File mailing list messages (subscribed as "ken+mta-filters"). -if envelope :detail "to" "mta-filters" { - fileinto "inbox.ietf-mta-filters"; -} - -# If a message is not to me (ignoring +detail), junk it. -if not allof (address :user ["to", "cc", "bcc"] "ken", address :domain ["to", "cc", "bcc"] "example.org") { - discard; -}</code></pre> - </li> - - <li> relational - <p> - The RELATIONAL extension provides relational operators on the - address, envelope, and header tests. This extension also provides a - way of counting the entities in a message header or address field. - </p> - Example: -<pre><code>require ["relational", "comparator-i;ascii-numeric"]; - -if header :value "lt" :comparator "i;ascii-numeric" ["x-priority"] ["3"] { - fileinto "Priority"; -} elseif address :count "gt" :comparator "i;ascii-numeric" ["to"] ["5"] { - # everything with more than 5 recipients in the "to" field - # is considered SPAM - fileinto "SPAM"; -} elseif address :value "gt" :all :comparator "i;ascii-casemap" ["from"] ["M"] { - fileinto "From N-Z"; -} else { - fileinto "From A-M"; -} - -if allof ( address :count "eq" :comparator "i;ascii-numeric" ["to", "cc"] ["1"] , address :all :comparator "i;ascii-casemap" ["to", "cc"] ["me...@fo...valid"] { - fileinto "Only me"; -}</code></pre> - </li> - - <li> comparator-i;ascii-numeric - <p> - The numeric value can be compared to specific values using the SIEVE relational - extension in conjunction with the "i;ascii-numeric" - comparator, which will test for the presence of a numeric - value at the start of the string, ignoring any additional text in the - string. The additional text can be used to carry implementation - specific details about the tests performed and descriptive comments - about the result. - The "i;ascii-numeric" comparator, MUST be - supported for any implementation of this extension. The comparator - "i;ascii-numeric" MUST support at least 32 bit unsigned integers. - </p> - Example: -<pre><code>require ["spamtest", "fileinto", "relational", "comparator-i;ascii-numeric"]; - -if spamtest :value "eq" :comparator "i;ascii-numeric" "0" { - fileinto "INBOX.unclassified"; -} elsif spamtest :value "ge" :comparator "i;ascii-numeric" "3" { - fileinto "INBOX.spam-trap"; -}</code></pre> - </li> - - <li> regex - <p> - Commands that support matching may take the optional tagged argument - ":regex" to specify that a regular expression match should be - performed. The ":regex" match type is compatible with both the "i;octet" and - "i;ascii-casemap" comparators and may be used with them. - </p> - Example: -<pre><code>require "regex"; -# Try to catch unsolicited email. -if anyof ( - # if a message is not to me (with optional +detail), - not address :regex ["to", "cc", "bcc"] "me(\\\\+.*)?@company\\\\.com", - - # or the subject is all uppercase (no lowercase) - header :regex :comparator "i;octet" "subject" "^[^[:lower:]]+$" - ) { - discard; # junk it -}</code></pre> - </li> - - </ul> -</div> - -<div id="Examples" class="section" title="Script Examples"> +<div id="Examples" class="section" title="More Script Examples"> <p> <a href="http://wiki.fastmail.fm/index.php/SieveVacation">Vacation Examples</a> + </p> <p> @@ -274,6 +333,7 @@ <ul> <li> <a href="http://www.rfc-archive.org/getrfc.php?rfc=3598"> + RFC3598 - Sieve Email Filtering - Subaddress Extension </a> </li> @@ -284,6 +344,7 @@ </li> <li> <a href="http://www.rfc-archive.org/getrfc.php?rfc=3028"> + RFC3028 - Sieve - A Mail Filtering Language </a> </li> @@ -293,7 +354,9 @@ </a> </li> <li> + <a href="http://www.rfc-archive.org/getrfc.php?rfc=3685"> + RFC 3685 - Sieve Email Filtering - Spamtest and VirusTest Extensions </a> </li> @@ -301,4 +364,5 @@ </div> </body> -</html> \ No newline at end of file +</html> + This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |