2005-10-08 [colin] 1.9.15cvs22
[claws.git] / doc / manual / en / sylpheed-13.html
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
2 <html>
3 <head>
4   <meta name="GENERATOR" content="LinuxDoc-Tools 0.9.21">
5   <title>Sylpheed-Claws User's Manual: Filters, actions and templates</title>
6   <link href="sylpheed-14.html" rel="next">
7   <link href="sylpheed-12.html" rel="previous">
8   <link href="sylpheed.html#toc13" rel="contents">
9 </head>
10 <body>
11 <a href="sylpheed-14.html">Next</a>
12 <a href="sylpheed-12.html">Previous</a>
13 <a href="sylpheed.html#toc13">Contents</a>
14 <hr>
15 <h2><a name="s13">11.</a> <a href="sylpheed.html#toc13">Filters,
16 actions and templates</a></h2>
17 <p>Sylpheed-Claws offers three powerful tools to help you automatically
18 and efficiently manage your mails. These tools are:</p>
19 <p>
20 </p>
21 <ul>
22   <li>The <i>filters</i>, that let you sort you incoming messages and
23 move
24 them into your folders based on their sender, their content,
25 using regular expressions.</li>
26   <li>The <i>actions</i> feature is a convenient way for the user to
27 launch external commands to process a complete message file including
28 headers and body or just one of its parts.
29 It allows also the use of an external command to filter the whole text
30 or just a selected part in the message window or in the compose window.</li>
31   <li>The <i>templates</i> that let you pre-define complete messages
32 leaving placeholders in the text to be filled at composition time.</li>
33 </ul>
34 <p></p>
35 <h2><a name="ss13.1">11.1</a> <a href="sylpheed.html#toc13.1">Filters</a>
36 </h2>
37 <p>Written by Nick Selby (sylpheed@nickselby.com)</p>
38 <p>Sylpheed-Claws provides powerful filters to allow users to
39 automatically pre-sort incoming mail based on a set of rules that the
40 user defines. As a most simple example, let's say you work at the Acme
41 Grommet Company, and you want all e-mail from your co-workers to be
42 placed in one mailbox. To accomplish this, you would set up a filter
43 that would place all mail whose "From" header includes the phrase
44 "acmegrommet.com" into a specific mailbox.</p>
45 <p>Sylpheed-Claws allows you much more control than just that simple setup;
46 you may create filters based on several variables, including an "If
47 this AND that" or "If the message contains this OR does NOT contain
48 that"
49 etc. <br>
50 </p>
51 <h3>Finding The Filter Setting Dialog</h3>
52 <p>The filter settings dialog is located in the <i>Configuration</i>
53 menu, under the title "Filter Setting" or from the <i>Tools</i> menu,
54 under in
55 the <i>Create filter rules</i> sub menu. You may also use establish a
56 keyboard shortcut (see Keyboard Shortcuts).</p>
57 <h3>Setting Up Filters</h3>
58 <p>Name, Condition(s) and Action instructions combine to create a
59 Filter Rule.</p>
60 <p>The Name is optional. It's there to help you find your rules back.</p>
61 <p>Condition(s):
62 The dialog's second setting option establishes the Conditions, the
63 variable that will tell the filter what specific text to look for to
64 trigger a filter. Each Filter Rule may have up to two conditions sets.</p>
65 <p>Each Condition variable contains three sections: <i>Header</i>, <i>Keyword</i>
66 and <i>Predicate</i>.</p>
67 <p>Header is a drop-down box which defines in which message header
68 Sylpheed's filter will search. Choices range from <i>Subject</i> to <i>X-Mailer</i>.
69 </p>
70 <p><i>Keyword</i> is a a text box in which you may enter the text for
71 which the filter will search. </p>
72 <p><span style="font-style: italic;">Predicate</span> allows you to
73 choose to filter based on whether the operator contains, or does not
74 contain, the text you enter in the Keyword field.</p>
75 <p>Example: Create a Condition in which the X-Mailer field of an
76 incoming message contains the word 'Eudora'.</p>
77 <p>
78 </p>
79 <ul>
80   <li>Step 1. Under the <i>Header</i> drop-down box, select <i>X-Mailer</i>.</li>
81   <li>Step 2. In the <i>Keyword</i> text box, type 'eudora' (case
82 insensitive)</li>
83   <li>Step 3. Determine appropriate <span style="font-style: italic;">Predicate</span>
84 setting. Default is <i>Contains</i>.</li>
85 </ul>
86 <p></p>
87 <p>The second Condition setting, which is set identically to the first,
88 also allows the user to select an AND/OR setting declaring the
89 relationship between the two operators. </p>
90 <p>Example: Create a Condition set which will process mail with a <i>From</i>
91 header of bob@acmegrommet.com AND a subject
92 of "2001 Spring Grommet Collection"</p>
93 <p>
94 </p>
95 <ul>
96   <li>Step 1. Under the first Condition set's Header drop-down box,
97 select <i>From</i>.</li>
98   <li>Step 2. In the <i>Keyword</i> text box, type
99 'bob@acmegrommet.com' (case insensitive).</li>
100   <li>Step 3. Leave <i>Predicate</i> setting on default, <i>Contains</i></li>
101   <li>Step 4. Leave <i>AND/OR</i> box on default setting, <i>and</i>.</li>
102   <li>Step 5. Under the second Condition set's <i>Header</i> drop-down
103 box, select <i>Subject</i>.</li>
104   <li>Step 6. In the <i>Keyword</i> text box, type '2001 spring
105 grommet collection' (case insensitive).</li>
106   <li>Step 7. Leave <i>Predicate</i> setting on default,
107     <i>Contains</i>.</li>
108 </ul>
109 <p></p>
110 <h3>Message Processing</h3>
111 <p>Once you've established the Condition(s) that will define which
112 messages will be processed, it's time to tell Sylpheed-Claws what to do with
113 messages that match the condition(s). You may choose between a few
114 operations such as Move, Copy, Mark, ...</p>
115 <p>Selecting <span style="font-style: italic;">Actions </span>will
116 enable you to choose what kind of action you want. Then you can choose
117 the value for the action (Destination, Score, Recipient, depending of
118 the type of the action).</p>
119 <h3>Filter Registration</h3>
120 <p>Now that you have set the Name, Condition(s) and the Action, all
121 that's left to do is tell Sylpheed-Claws to save the entire Filter Rule. <b>If
122 you skip this step, the filter won't work</b>.</p>
123 <p>The <i>Register Rules</i> configuration has three options: <span
124  style="font-style: italic;">Add, Replace</span> and <i>Delete</i>. </p>
125 <p>
126 </p>
127 <ul>
128   <li><i>Add </i>saves the Filter Rule.</li>
129   <li><i>Replace </i>modifies an existing registered Filter Rule.</li>
130   <li><i>Delete</i> will remove a previously registered Filter Rule. </li>
131 </ul>
132 <p></p>
133 <p>Example of adding a filter rule: Create a Filter Rule that moves all
134 mail with the subject of "Sylpheed-Claws Manual" into the (previously
135 created) mail folder "Sylpheed-Claws Manual Mail".</p>
136 <p>
137 </p>
138 <ul>
139   <li>Step 1. Under the first Condition set <i>Header</i> drop-down
140 box, select <i>Subject</i>.</li>
141   <li>Step 2. In the <i>Keyword</i> text box, type 'sylpheed manual'
142 (case insensitive).</li>
143   <li>Step 3. Leave <i>Predicate</i> setting on default, <i>Contains</i>.
144     <br>
145   </li>
146   <li>Step 4. Click Add.</li>
147   <li>Step 5. Click OK.</li>
148   <li>Step 6. Click the Action's Define button; select Move and
149 "Sylpheed-Claws Manual Mail" folder.</li>
150   <li>Step 7. Click Add.</li>
151   <li>Step 8. Click <i>OK</i>.</li>
152   <li>Step 9. Click Add.</li>
153   <li>Step 10. Click OK.</li>
154 </ul>
155 <h3>Registered Rule Order</h3>
156 <p>One caveat about all this: the order in which Filter Rules are
157 created could adversely affect your intended message sorting, and one
158 needs to consider this when creating or updating Filter Rules. </p>
159 <p>For example, a Filter Rule saying, "Move anything containing 'ABC'
160 to Mailbox X" listed above another Filter Rule saying "Move anything
161 containing 'ABCDEF' to Mailbox Y" will cause the latter of these
162 filters not to process. </p>
163 <p>Think about the way Sylpheed-Claws goes down its list: first, it would
164 say..
165 "Hmm, any messages with ABC? Ah, there's one! Move it". Then it would
166 think, "Okay, any messages with ABCDEF?" To which the answer would be
167 "no" - that ABCDEF was already filtered because it contained "ABC".</p>
168 <p>This isn't what we want, is it?</p>
169 <p>In order to avoid this, you must ensure that the more complex Filter
170 Rule is processed first, by placing it higher than a similar,
171 conflicting Filter Rule. </p>
172 <p>To move a Registered Rule higher or lower within the Registered Rule
173 box, select the rule you would like to move, and click on the <i>Up</i>
174 or <i>Down</i> buttons. This will "move" the rule up or down, above or
175 below a potentially conflicting Filter Rule. </p>
176 <h2><a name="ss13.2">11.2</a> <a href="sylpheed.html#toc13.2">How to
177 Filter Messages</a>
178 </h2>
179 <p>Filtering messages can be done in several ways:</p>
180 <p>
181 </p>
182 <ul>
183   <li>Sylpheed-Claws automatically filters incoming mail if the checkbox <span
184  style="font-style: italic;">Filter messages on receiving </span>is
185 checked in the account's preferences Receive tab..</li>
186   <li>You can also select the option <i>Filter messages</i> from the
187 Summary menu.</li>
188 </ul>
189 <h2><a name="ss13.3">11.3</a> <a href="sylpheed.html#toc13.3">Filtering
190 mail with Procmail</a>
191 </h2>
192 <p>Another option is Procmail. Procmail is a powerful mail filtering
193 program that is triggered from the Mail Transport Agent (i.e. Sendmail,
194 Postfix, Qmail). Procmail is called by default from these programs
195 after receiving e-mail.</p>
196 <p>The trick to procmail is to tell it that mail has to be filtered
197 into MH mail folders. This is not difficult though.</p>
198 <p>Normally procmail moves mail into MBOX format, this is one large
199 file containing all mails in a folder. MH uses separate files for each
200 e-mail. All you need to do is point the destination of a procmail rule
201 to &lt;destination folder&gt;/. It is the "slash dot" that does the
202 trick.</p>
203 <h2><a name="ss13.4">11.4</a> <a href="sylpheed.html#toc13.4">Actions</a>
204 </h2>
205 <p>The following section is a copy of <a
206  href="http://melvin.hadasht.free.fr/home/sylpheed/actions/index.html">Melvin's
207 page</a>.</p>
208 <p>The "actions" feature is a convenient way for the user to launch
209 external commands to process a complete message file including headers
210 and body or just one of its parts. It allows also the use of an
211 external command to filter the whole text or just a selected part in
212 the message window or in the compose window. This is a generic tool
213 that allows to do any uncommon actions on the messages, and thus
214 extends the possibilities of Sylpheed. For example, Sylpheed-Claws does not
215 include the rot13 cyphering algorithm popular in some newsgroups. It
216 does not support natively armored encryption or clear signing. It does
217 not support uuencoded messages. As all these features can be handled by
218 external programs, the actions provide a convenient way to use them
219 from the menu bar.</p>
220 <h3>Usage</h3>
221 <p>To create a new action, go to the <i>Configuration</i> menu,
222 select the <i>Actions...</i> entry. The <i>Actions setting</i>
223 dialog offers to enter the Menu name that will trigger the command. The
224 created menu will be found in the <i>Tools -&gt; Actions</i> submenu.
225 By inserting a slash / in the menu name, you create a submenu.</p>
226 <p>The command is entered in the Command line entry. Note that Sylpheed
227 stores every single email in a separate file. This allows to use the
228 following syntax for the command:</p>
229 <p>
230 </p>
231 <ul>
232   <li><i>%f</i> denotes the file name of the selected message. If you
233 selected more than one, then the command will be launched for each
234 message with the appropriate file name.</li>
235   <li><i>%F</i> denotes the list of the file names of the selected
236 message. If only one message is selected, this amounts to <i>%f</i>,
237 but if more messages are selected, then the command will be launched
238 only once with the list of the file names. (You can use both <i>%f</i>
239 and <i>%F</i> in one command: then the command will be launched for
240 each selected message with the name of this message and with the list
241 of all selected messages. I did not find a practical example for this.).</li>
242   <li><i>%p</i> denotes the current selected message part of a
243 multipart message. The part is decoded accordingly. If the message is
244 not a multipart message, it denotes the message body.</li>
245   <li>Prepending <i>&gt;</i>: this will allow you to send to the
246 command's standard input a text that you will enter in a dialog window.</li>
247   <li>Prepending <i>*</i>: this will allow you to send to the
248 command's standard input a text that you will enter in a dialog window.
249 But in contrast to prepending <i>&gt;</i>, the entered text is hidden
250 (useful when entering passwords).</li>
251   <li>Appending an ampersand <i>&amp;</i>: this will run the command
252 asynchronously. That means "fire and forget". Sylpheed-Claws won't wait for
253 the command to finish, nor will it catch its output or its error
254 messages.</li>
255   <li>Prepending the vertical bar <i>|</i> (pipe-in): this will send
256 the current displayed text or the current selected text from the
257 message view or the compose window to the command standard input. The
258 command will silently fail if more than one message is selected.</li>
259   <li>Appending the vertical bar <i>|</i> (pipe-out): this will
260 replace the current displayed text or the current selected text from
261 the message window or the compose window with the command standard
262 output. The command will silently fail if more than one message is
263 selected.</li>
264   <li>Appending the "greater than" sign <i>&gt;</i> will insert the
265 command output in the message. The difference between the trailing <i>|</i>
266 is that no text will be deleted or replaced. Most used when composing
267 mails to insert text.</li>
268 </ul>
269 <p></p>
270 <p><b>Note</b>: It is not possible to use actions containing <i>%f</i>,
271 <i>%F</i> or <i>%p</i> from the compose window.</p>
272 <p>When a command is run, and unless it is run asynchronously, Sylpheed
273 will be insensitive to any interaction and it will wait for the command
274 to finish. If the command takes too long (5 seconds), it will popup a
275 dialog window allowing to stop it. This dialog will also be displayed
276 as soon as the command has some output: error messages or even its
277 standard output when the command is not a "pipe-out" command. When
278 multiple commands are being run, they are run in parallel and each
279 command output is separated from the outputs of the others.</p>
280 <h3>Examples</h3>
281 <p>Here are some examples that are listed in the same syntax as used
282 for storing the actions list. You can copy and past the definition in
283 your <i>&nbsp;/.sylpheed/actionsrc</i> file (exit Sylpheed-Claws before).
284 The syntax is very simple: one line per action, each action contains
285 the menu name and the command line separated by a colon and a space ":
286 ". Alternatively, you can use <i>Configuration -&gt; Actions...</i>
287 and for each example enter a menu name and copy&amp;paste the text
288 after the colon and space ": " in the command definition.</p>
289 <p>
290 <br>
291 </p>
292 <center>
293 <table border="1">
294   <tbody>
295     <tr>
296       <td><b>Purpose</b></td>
297       <td><b>Definition</b></td>
298       <td><b>Details</b></td>
299     </tr>
300     <tr>
301       <td>Decoding uuencoded messages</td>
302       <td>UUdeview: xdeview %F&amp;</td>
303       <td>xdeview comes with uudeview. If an encoded file is splitin
304 multiple messages, just select them all and run the command.</td>
305     </tr>
306     <tr>
307       <td>Display uuencoded image</td>
308       <td>Display uuencoded: uudec %f&amp;</td>
309       <td>Displays uuencoded files. The uudec script is to be found
310 here.</td>
311     </tr>
312     <tr>
313       <td>rot13 cyphering</td>
314       <td>Rot13: |tr a-zA-Z n-za-mN-ZA-M|</td>
315       <td>This will apply the rot13 cyphering algorithm to the
316 (selected)text in the message/compose view.</td>
317     </tr>
318     <tr>
319       <td>Save MS TNEF parts</td>
320       <td>Save TNEF part: xterm -e tnef-claws %p</td>
321       <td>Select the TNEF message part then use this action to
322 extractthe attachment.</td>
323     </tr>
324     <tr>
325       <td>Alter messages</td>
326       <td>Edit message: gvim -f %F</td>
327       <td>Allows to edit any received message. Can be used to
328 removeunneeded message parts etc.</td>
329     </tr>
330     <tr>
331       <td>Pretty format</td>
332       <td>Par: |par 72Tbgjqw74bEe B=._A_a 72bgi|</td>
333       <td>par is a utility that can pretty format any text. It does
334 avery good job in indenting quoted messages, and justify text.Used when
335 composing a message</td>
336     </tr>
337     <tr>
338       <td>Browse</td>
339       <td>Part/Dillo: dillo %p&amp;</td>
340       <td>Browse the selected message part in Dillo.</td>
341     </tr>
342     <tr>
343       <td>Clear Sign</td>
344       <td>GnuPG/Clear Sign: |gpg-sign-syl|</td>
345       <td>Clear sign a message. The gpg-sign-syl script is
346 responsiblefor asking the passphrase and for running gnupg. Make
347 surethat you wrap your message correctly before signing, and thatthe
348 resultant text will not be wrapped when sent (by disabling'wrap on
349 send')</td>
350     </tr>
351     <tr>
352       <td>Verify Clear Signed</td>
353       <td>GnuPG/Verify: |gpg --no-tty --verify</td>
354       <td>Verify clear signed messages. The result is displayed in
355 theactions output dialog.</td>
356     </tr>
357     <tr>
358       <td>Encrypt ASCII Armored</td>
359       <td>GnuPG/Encrypt: | gpg-enc-syl|</td>
360       <td>Encrypt message to ASCII armored. The recipient will be
361 askedin a xterm.</td>
362     </tr>
363     <tr>
364       <td>Decrypt ASCII Armored</td>
365       <td>GnuPG/Decrypt: *gpg --no-tty --command-fd 0 --passphrase-fd 0
366 --decrypt %f|</td>
367       <td>Decrypt ASCII armored messages. The passphrase is to be
368 enteredin the opened action's input dialog.</td>
369     </tr>
370     <tr>
371       <td>Receive key from server</td>
372       <td>GnuPG/Receive Selected Key: |gpg --recv-key `cat`</td>
373       <td>Select a key ID in the message view then call this action
374 toimport it from a key server. GnuPG option file must contain
375 areference to a keyserver. (Suggested by Bob Forsman)</td>
376     </tr>
377     <tr>
378       <td>Import key from mail</td>
379       <td>GnuPG/Import Key From Mail: gpg --import %p</td>
380       <td>Select the message part where the public key is then importit
381 with this action.</td>
382     </tr>
383     <tr>
384       <td>Insert public key in message</td>
385       <td>GnuPG/Insert My Public Key: gpg --export -a MYKEYID&gt;</td>
386       <td>Insert your public key in the message your are
387 composing.Replace MYKEYID with your key id. Needs 0.8.6claws66 or newer.</td>
388     </tr>
389     <tr>
390       <td>Reporting SPAM</td>
391       <td>Report as SPAM: spamassassin -r &gt; %f</td>
392       <td>Use spamassassin to report mail as spam. Redirection (&gt;)is
393 possible only with version 0.7.7.</td>
394     </tr>
395     <tr>
396       <td>Check spelling</td>
397       <td>Check spelling: |T=`mktemp $HOME/.sXXXXXX`; cat - &gt;
398 $T;xterm -e ispell $T;cat $T;rm $T|</td>
399       <td>Open a terminal and check the spelling with ispell</td>
400     </tr>
401     <tr>
402       <td>Google for message id</td>
403       <td>Google Msg ID: |google&thinsp;msgid.pl</td>
404       <td>Search the web for the selected message ID. Needs
405 thegoogle&thinsp;msgid.pl script.</td>
406     </tr>
407     <tr>
408       <td></td>
409     </tr>
410   </tbody>
411 </table>
412 </center>
413 <br>
414 <p></p>
415 <p>The gpg-enc-syl script is to be found <a
416  href="http://melvin.hadasht.free.fr/home/sylpheed/actions/gpg-enc-syl">here
417 (gpg-enc-syl)</a>. It calls gpg with the --yes command line option that
418 you may want to remove it. See gpg manual page for info.</p>
419 <p>The gpg-sign-syl script is to be found <a
420  href="http://melvin.hadasht.free.fr/home/sylpheed/actions/gpg-sign-syl">here
421 (gpg-sign-syl)</a>. It needs the ssh-askpass utility found in OpenSSH.
422 It can be replaced by any X11 tool that asks some (hidden) text which
423 is then sent to standard output. Another version that uses an xterm is
424 to be found <a
425  href="http://melvin.hadasht.free.fr/home/sylpheed/actions/gpg-sign-syl-xterm">here
426 (gpg-sign-syl-xterm)</a>.</p>
427 <p>The uudec script is to be found <a
428  href="http://melvin.hadasht.free.fr/home/sylpheed/actions/uudec">here
429 (uudec)</a>.
430 It needs uudecode and ImageMagick's display. The latter can be
431 replaced by any image viewer that can get input from standard input.
432 The script could also be modified to use temporary files instead of
433 standard input.</p>
434 <p>The google_msgid.pl script is to be found <a
435  href="http://melvin.hadasht.free.fr/home/sylpheed/actions/google_msgid.pl">here
436 (google_msgid.pl)</a>. Example and script by Thorsten Maerz. Edit the
437 script to change the browser (default is mozilla).</p>
438 <p>The tnef-claws bash script was written by Shawn Lamson and is to be
439 found <a
440  href="http://melvin.hadasht.free.fr/home/sylpheed/actions/tnef-claws">here</a>.
441 The script is well commented. You need to have the tnef package already
442 installed.</p>
443 <h2><a name="ss13.5">11.5</a> <a href="sylpheed.html#toc13.5">Templates</a>
444 </h2>
445 <p>With Sylpheed-Claws you can define mail templates to use when replying
446 to messages. A template can contain raw text (that will be inserted
447 in the composed mail without any change), and placeholders that are
448 replaced at composition time by the actual value of the selected
449 fields from the original message.</p>
450 <p>A typical use of the template could be to define the legal notice
451 to be appended to your messages (the usual notice that contains a
452 text like: "here are my own words and not those of my company, my
453 boss is not liable for them, bla, bla, bla").</p>
454 <p>To define a new template, in the <i>Configuration</i> menu select
455 the <i>Templates</i> entry and fill the form:</p>
456 <p>The name parameter is used to identify each template, this name
457 will then appear in the <i>Tools/Templates</i> menu in the
458 composition window.
459 The content of the <i>To</i> field will be appended to the original
460 content of the corresponding field in the message you are composing.
461 The content of the <i>Subject</i> field will replace the orignal
462 subject
463 of the message you are composing.</p>
464 <p>In the upper pane, type in the text you want to put in the template,
465 use the <i>Symbols</i> button to open a help window that contains
466 the description of all the placeholders you can use in a template
467 (there is one for the sender, one for the date, one for the message
468 ID, ...), then use the <i>Register</i> button to validate the
469 template. If you do not register the template, when leaving the form
470 the template will be canceled. To modify an existing template, select
471 it in the lower pane, modify its text, then use the <i>Substitute</i>
472 button. As you may guess, the <i>Delete</i> button removes the
473 selected
474 template. Finally validate your changes with the <i>OK</i> button.
475 If you use the <i>Cancel</i> button, the form is closed and your
476 changes
477 are lost (deleted templates are back, added templates are lost).</p>
478 <p>To use a template, open the composition window and select the
479 template
480 from the <i>Tools/Templates</i> menu. You can then choose to insert
481 the template into your message or to completely replace the text of the
482 message by the template. This only affects the body of the message.
483 If you choose to insert the template, its text will be inserted at the
484 cursor location.</p>
485 <p>The placeholders are taken from the source message when replying, so
486 they have no meaning when composing a new message.</p>
487 <hr>
488 <a href="sylpheed-14.html">Next</a>
489 <a href="sylpheed-12.html">Previous</a>
490 <a href="sylpheed.html#toc13">Contents</a>
491 </body>
492 </html>