Changes between Version 5 and Version 6 of Documentation/Configuration

Timestamp:

Oct 28, 2012 11:53:15 AM (7 months ago)

Author:

damato

Comment:

--

Documentation/Configuration

@@ -196 +196 @@
 
   Example: RX PROGDIR:rexx/Newmail.YAM
+
+== Filters ==
+The purpose of a mail filter is to process mail according to criteria defined by the user.  Whenever a mail matches a specified pattern, it can
+trigger certain actions. Applications for the use of filters include
+
+- automatically moving mail from a mailing list to a specified folder
+
+- automatic processing of incoming inquiries by sending pre-defined
+  answers
+
+- automatic deletion of unwanted spam (advertising by e-mail, a real
+  pest nowadays)
+
+- automatic re-directing of mails to another recipient.
+
+You can define theoretically an unlimited number of filters. The list on the left shows the names of all the filters defined so far. Click on a name to bring up its details on the right, spread across three sheets -- Options, Comparison and Action. Click on [New] to create a new filter or use [Delete] to delete one. Filters are executed in top-to-bottom order, therefore you should place filters that delete or move messages at the bottom of the list.
+
+=== Options ===
+`Name`
+  The filter's name is merely for recognition and not of any other use.
+
+`Remote filter`
+  With a remote filter, new email can be checked on the POP3 server without being downloaded completely. The POP3 server must support the TOP command to be able to process this kind of filter.
+  In contrast to 'normal' filters, only the contents of the e-mail headers can be searched for certain patterns. For obvious reasons, functions like forwarding or moving e-mails cannot be used with remote filters. In addition, if remote filters are activated they might slow down downloading e-mail, but they are handy and powerful if used with care.
+
+`Apply to new mail`
+  Activate this option to have all new mail processed by this filter. Processing will start automatically after receiving new mail.
+
+`Apply to sent mail`
+  Activate this option to have all sent mail processed by this filter. Processing will be initiated automatically after sending mail.
+
+`Apply on request`
+  If this option is activated, the filtering process will be started by clicking on the Filter button in the main window or by choosing 'Filter' from the 'Folder' menu. This way you can also process old messages which do not necessarily have to be in the Incoming folder.
+
+=== Comparison ===
+`Search in`
+  Here you can define what part of the e-mail should be scanned for the search pattern. If you want a field of the message header to be searched, you can choose one from the list which appears when clicking on the cycle gadget, or select 'Other field' and insert the name of the header field into the text field on the right side of the cycle gadget. If 'Message body' is selected, the whole message -except for the headers- will be searched.  Please note that this type of full text search may take quite a long time when big mails are processed (YAM will have to decode mails in MIME format).
+
+  Example: 'Other field: X-Mailer'
+
+`Comparison`
+  The instruction comprises the comparison operator and the search pattern.
+
+  YAM supports the following comparison operators:
+
+  - //=//  the text which is compared must match the search pattern
+  - //<//  the text must be "less" than the search pattern
+  - //>//  the text must be "greater than" the search pattern
+  - //<>// the text must be different from the search pattern
+  - //IN// the text must match pattern contained in the file which is specified in the text field to the right side of the comparison cycle gadget.  Instead of a search pattern itself, the name of a file has to be inserted here, containing one or several lines of search patterns. In this way it is possible to create a so-called 'Killfile' containing a list of e-mail addresses. Click on the page icon to edit the file.
+
+  Note that the comparison operators '<' and '>' work differently according to the type of field.  YAM knows that a message size or date is numeric and sorts these in numerical order, but for fields such as "Subject:", alphanumeric order is used as in a telephone directory, so James < Jim and 12 < 2.
+
+  The search pattern may contain  AmigaDOS wildcards  such as ?, #?, (a|b) or [abc]. Please note that the search pattern [YAM]#? will filter all messages beginning with Y, A or M. For filtering mails coming from a mailing list (for example, a mailing list related to YAM), you'd better use the search pattern #?YAM#? or have the filter compare the Reply-To: field with the address of the mailing list.
+
+  Example: '= YAM 1.3.#?'
+
+`Address/Name`
+  If you make the filter search a header field containing an e-mail address, you can specify here whether the search pattern should be processed on the actual address (e.g. jdoe@example.com) or the author's name (e.g. 'John Doe').
+
+`Case sensitive`
+  Activate this option if you want the filtering process to distinguish between normal and capital letters.
+
+`Substring search`
+  If the search pattern consists of only a part of the header field which is to be searched through, you must activate this option - YAM will then complete the search pattern with #? internally.
+
+  It is possible to combine two search criteria. The cycle gadget lets you select how this is to be done:
+
+  //none// don't use a second criterion
+  //and//  both criteria must be satisfied
+  //or//   at least one of the two criteria must be met
+  //exclusive or// either one or the other of the two criteria must apply, but not both
+
+=== Action ===
+
+`Bounce`
+  Activate this option to have mail matching the search criteria bounced to another recipient -- for instance, you might use this to automatically resend certain email to your mailbox at work.
+
+  The new recipient's e-mail address must be inserted into the text field next to the option.
+
+  Example: jdoe@example.net
+
+`Forward`
+  Activate this option when you want e-mail matching the search criteria to be forwarded to another person.  The new recipient's e-mail address must be inserted into the text field next to the option.
+
+`Reply`
+  If this option is activated, YAM will send an automatic reply to any mail matching the search pattern. Enter the filename containing the auto-answer text into the text field next to this option.
+
+  Example: PROGDIR:Auto-Texts/Answer1.txt
+
+`Execute`
+  If this option is activated, an external program will be executed whenever an email matches the search criterion. YAM will send the path of the e-mail to the external program as a starting parameter. Insert the command line into the text field next to this option.
+
+  Please note that if you want an ARexx script to be executed, you will have to explicitely put the 'RX' command first.
+
+  Example: 'rx PROGDIR:Rexx/Subscribe.rexx'
+
+`Play sound`
+  Activate this option to have a sound played whenever a message matches the search pattern.  The sound file name is to be inserted into the text field next to this option.  YAM uses the datatypes library for playing the sound.  Click the small arrow (PLAY symbol) to test the sound.
+
+  Example: Data:Audio/Ihatespam.wav
+
+`Move`
+  If you activate this option, YAM will move any email matching the search pattern to another folder. You can select the folder with the pop-up button.
+
+
+`Delete`
+  If this option is activated, all messages matching the search pattern will be deleted. (You probably guessed that... ;) )
+
+
+`Don't download`
+  If this option is activated, any message matching the search pattern will not be downloaded from the mail server. You can use a remote filter together with this option if several people share the same POP3 account.