1 |
.Dd December 4, 2001 |
.Dd February 15, 2004 |
2 |
.Dt IMAPFILTERRC 5 |
.Dt IMAPFILTERRC 5 |
3 |
.Os |
.Os |
4 |
.Sh NAME |
.Sh NAME |
19 |
are considered comments, are ignored. |
are considered comments, are ignored. |
20 |
.Sh COMMANDS |
.Sh COMMANDS |
21 |
.Bl -tag -width Ds |
.Bl -tag -width Ds |
22 |
.It Cm account Ar username:password@hostname[:port] [ssl|ssl2|ssl3|tls1] |
.It Cm account Ar alias username[:password]@hostname[:port] [ssl2|ssl3|tls1] |
23 |
Defines a user account, using the |
Defines a user account under the name |
24 |
|
.Ar alias , |
25 |
|
using the |
26 |
.Ar username |
.Ar username |
27 |
as user identification and |
as user identification and |
28 |
.Ar password |
.Ar password |
30 |
.Ar hostname |
.Ar hostname |
31 |
mail server, at the specified |
mail server, at the specified |
32 |
.Ar port |
.Ar port |
33 |
(if not specified the default IMAP protocol port (ie. 143 or 993 when SSL/TLS is |
(if not specified the default IMAP protocol port (ie. 143 for imap and 993 |
34 |
enabled) is used). SSL/TLS support is enabled with the argument |
for imaps) is used). |
35 |
.Ar ssl , |
.Pp |
36 |
which uses as default the SSL protocol version 2, though this may be changed by |
SSL encrypted connection (imaps) is enabled with the argument |
37 |
specifying a different protocol/version. |
.Ar ssl2 , |
38 |
|
.Ar ssl3 , |
39 |
|
or |
40 |
|
.Ar tls1 . |
41 |
|
.Pp |
42 |
|
The |
43 |
|
.Ar alias |
44 |
|
is comprised by alphanumeric, underscore |
45 |
|
.Sq _ |
46 |
|
and minus |
47 |
|
.Sq - |
48 |
|
characters. |
49 |
.Pp |
.Pp |
50 |
The |
The |
51 |
.Ar username |
.Ar username |
56 |
character followed by two hexadecimal digits representing the encoded |
character followed by two hexadecimal digits representing the encoded |
57 |
character's |
character's |
58 |
.Xr ascii 7 |
.Xr ascii 7 |
59 |
code. Within the |
code. Within the |
60 |
.Ar username |
.Ar username |
61 |
and |
and |
62 |
.Ar password |
.Ar password |
63 |
field, any |
field, any |
64 |
.Sq \&: , |
.Sq \&: , |
65 |
.Sq @ |
.Sq @ , |
|
or |
|
66 |
.Sq % |
.Sq % |
67 |
|
or |
68 |
|
.Sq \ |
69 |
characters must be encoded in the above way. |
characters must be encoded in the above way. |
70 |
|
.Pp |
71 |
|
The |
72 |
|
.Ar password |
73 |
|
field may be omitted, in which case the user is prompted for one |
74 |
|
interactively, when |
75 |
|
.Xr imapfilter 1 |
76 |
|
is run. Also, a |
77 |
|
.Ar password |
78 |
|
must not be supplied, if the user intends to specify one using the |
79 |
|
interactive encrypted passwords' editor of |
80 |
|
.Xr imapfilter 1 , |
81 |
|
in order to store the password securely in the filesystem. |
82 |
.It Cm folder Ar alias folder[,...] |
.It Cm folder Ar alias folder[,...] |
83 |
Defines folders (mailboxes) and groups them under the |
Defines folders (mailboxes) and groups them under the |
84 |
.Ar alias |
.Ar alias |
85 |
name. The mailboxes are associated with the last preceding |
name. The mailboxes are associated with the last preceding |
86 |
.Ar account |
.Ar account |
87 |
setting. More than one |
setting. More than one |
88 |
.Ar folder |
.Ar folder |
89 |
can be declared, separating them with a comma |
can be declared, separating them with a comma |
90 |
.Sq \&, |
.Sq \&, |
91 |
character. The |
character. The |
92 |
.Ar alias |
.Ar alias |
93 |
is comprised by alphanumeric, underscore |
is comprised by alphanumeric, underscore |
94 |
.Sq _ |
.Sq _ |
105 |
flag can be set, in order to set the mode in which the filter's masks |
flag can be set, in order to set the mode in which the filter's masks |
106 |
will be combined (default is |
will be combined (default is |
107 |
.Ar and |
.Ar and |
108 |
mode). |
mode). The |
109 |
|
.Ar alias |
110 |
|
is comprised by alphanumeric, underscore |
111 |
|
.Sq _ |
112 |
|
and minus |
113 |
|
.Sq - |
114 |
|
characters. |
115 |
.It Cm [mask] Ar [or|and] [not] searchkey |
.It Cm [mask] Ar [or|and] [not] searchkey |
116 |
A filter entry contains one or more mask entries which are defined with |
A filter entry contains one or more mask entries which are defined with |
117 |
the optional |
the optional |
220 |
Messages that contain the specified string in the envelope structure's |
Messages that contain the specified string in the envelope structure's |
221 |
.Dq Subject |
.Dq Subject |
222 |
field. |
field. |
223 |
|
.It Cm to Ar string |
224 |
|
Messages that contain the specified |
225 |
|
.Ar string |
226 |
|
in the envelope structure's |
227 |
|
.Dq To |
228 |
|
field. |
229 |
.It Cm unanswered |
.It Cm unanswered |
230 |
Messages that have not been answered. |
Messages that have not been answered. |
231 |
.It Cm undeleted |
.It Cm undeleted |
242 |
.Cm action |
.Cm action |
243 |
command is used to end the filter entry started with the |
command is used to end the filter entry started with the |
244 |
.Cm filter |
.Cm filter |
245 |
command. It assigns an action to be done when the filter is matched. |
command. It assigns an action to be done when the filter is matched. |
246 |
.Pp |
.Pp |
247 |
The available |
The available |
248 |
.Ar type |
.Ar type |
253 |
.Ar mailbox . |
.Ar mailbox . |
254 |
If the |
If the |
255 |
.Ar mailbox |
.Ar mailbox |
256 |
does not exist, then it is created. Optionally, fetches and displays the |
does not exist, then it is created. |
257 |
|
.Pp |
258 |
|
Date and time conversion specifiers may be used in the name of the |
259 |
|
.Ar mailbox . |
260 |
|
Specifically, a conversion specification consists of a percent sign |
261 |
|
.Sq % |
262 |
|
and another character for the current local date and time of the system, |
263 |
|
and an at sign |
264 |
|
.Sq @ |
265 |
|
and another character for the date and time of the message processed. The |
266 |
|
characters used in the conversion specification are described in |
267 |
|
.Xr strftime 3 . |
268 |
|
.Pp |
269 |
|
The default variable |
270 |
|
.Dq $_ |
271 |
|
may be used in the name of the |
272 |
|
.Ar mailbox , |
273 |
|
which aliases to the name of the mailbox in which the filter is now applied. |
274 |
|
The |
275 |
|
.Dq $$ |
276 |
|
sequence is replaced by |
277 |
|
.Dq $ . |
278 |
|
.Pp |
279 |
|
The headers' variables |
280 |
|
.Dq &u , |
281 |
|
.Dq &d , |
282 |
|
.Dq &f , |
283 |
|
may be used in the name of the |
284 |
|
.Ar mailbox , |
285 |
|
which alias to the user, domain and user@domain of the message's |
286 |
|
.Dq From |
287 |
|
header, respectively. The |
288 |
|
.Dq && |
289 |
|
sequence is replaced by |
290 |
|
.Dq & . |
291 |
|
.Pp |
292 |
|
Optionally, fetches and displays the |
293 |
.Ar header |
.Ar header |
294 |
of the messages that were copied. |
of the messages that were copied. |
295 |
.It Cm delete Ar [header,...] |
.It Cm delete Ar [header,...] |
296 |
Deletes the messages. User can also, optionally, define the |
Deletes the messages. User can also, optionally, define the |
297 |
.Ar header |
.Ar header |
298 |
of the deleted messages to be displayed. More than one |
of the deleted messages to be displayed. More than one |
299 |
.Ar header |
.Ar header |
300 |
can be declared and fetched, by separating them with a comma |
can be declared and fetched, by separating them with a comma |
301 |
.Sq \&, |
.Sq \&, |
302 |
character. |
character. |
303 |
|
.It Cm flag Ar mode flag[,...] [header,...] |
304 |
|
Sets the flags of the messages. The |
305 |
|
.Ar mode |
306 |
|
can be |
307 |
|
.Ar replace , |
308 |
|
.Ar add , |
309 |
|
or |
310 |
|
.Ar remove . |
311 |
|
The |
312 |
|
.Ar flag |
313 |
|
can be |
314 |
|
.Ar none , |
315 |
|
.Ar seen , |
316 |
|
.Ar answered , |
317 |
|
.Ar flagged , |
318 |
|
.Ar deleted , |
319 |
|
or |
320 |
|
.Ar draft . |
321 |
|
Optionally, the |
322 |
|
.Ar header |
323 |
|
of the messages is displayed. |
324 |
.It Cm list Ar [header,...] |
.It Cm list Ar [header,...] |
325 |
Just displays the |
Just displays the |
326 |
.Ar header |
.Ar header |
330 |
.Ar mailbox . |
.Ar mailbox . |
331 |
If the |
If the |
332 |
.Ar mailbox |
.Ar mailbox |
333 |
does not exist, then it is created. Optionally, fetches and displays the |
does not exist, then it is created. Date and time conversion specifiers and |
334 |
|
the default and headers' variables may be used in the name of the |
335 |
|
.Ar mailbox |
336 |
|
(see the |
337 |
|
.Ar copy |
338 |
|
action for more information). Optionally, fetches and displays the |
339 |
.Ar header |
.Ar header |
340 |
of the messages that were moved. |
of the messages that were moved. |
341 |
|
.It Cm rcopy Ar account mailbox [header,...] |
342 |
|
Copies the messages to the specified |
343 |
|
.Ar mailbox |
344 |
|
residing on a specific |
345 |
|
.Ar account . |
346 |
|
Date and time conversion specifiers and the default and headers' variables may |
347 |
|
be used in the name of the |
348 |
|
.Ar mailbox |
349 |
|
(see the |
350 |
|
.Ar copy |
351 |
|
action for more information). Optionally, displays the |
352 |
|
.Ar header |
353 |
|
of the messages. |
354 |
|
Unlike all other |
355 |
|
.Ar type |
356 |
|
of actions, this requires that the message is downloaded from the source |
357 |
|
mail server and then uploaded to the target mail server. |
358 |
|
.It Cm rmove Ar account mailbox [header,...] |
359 |
|
Moves the messages to the specified |
360 |
|
.Ar mailbox |
361 |
|
residing on a specific |
362 |
|
.Ar account . |
363 |
|
Date and time conversion specifiers and the default and headers' variables may |
364 |
|
be used in the name of the |
365 |
|
.Ar mailbox |
366 |
|
(see the |
367 |
|
.Ar copy |
368 |
|
action for more information). Optionally, displays the |
369 |
|
.Ar header |
370 |
|
of the messages. |
371 |
|
Unlike all other |
372 |
|
.Ar type |
373 |
|
of actions, this requires that the message is downloaded from the source |
374 |
|
mail server and then uploaded to the target mail server. |
375 |
.El |
.El |
376 |
.It Cm job Ar filter[,...] folder[,...] |
.It Cm job Ar filter[,...] folder[,...] |
377 |
This command is used to define which |
This command is used to define which |
390 |
.El |
.El |
391 |
.Sh VARIABLES |
.Sh VARIABLES |
392 |
.Bl -tag -width Ds |
.Bl -tag -width Ds |
393 |
|
.It Va charset |
394 |
|
Indicates to the server the character set of the strings that appear in the |
395 |
|
search criteria. Character sets are defined in RFC 2978 and must be supported |
396 |
|
by the server. It takes a string as an argument. |
397 |
|
.It Va daemon |
398 |
|
Enables the daemon mode of |
399 |
|
.Xr imapfilter 1 . |
400 |
|
It takes a numeric |
401 |
|
argument, the polling interval in seconds. |
402 |
|
.It Va errors |
403 |
|
By enabling this option any error messages during program's execution get |
404 |
|
appended to the log file, besides being written to stderr. The argument |
405 |
|
must be |
406 |
|
.Dq yes |
407 |
|
or |
408 |
|
.Dq no . |
409 |
|
Default is |
410 |
|
.Dq no. |
411 |
|
.It Va expunge |
412 |
|
Normally messages are marked for deletion and are actually deleted when the |
413 |
|
mailbox is closed. When this option is enabled, messages are expunged after |
414 |
|
they are marked deleted. The argument must be |
415 |
|
.Dq yes |
416 |
|
or |
417 |
|
.Dq no . |
418 |
|
Default is |
419 |
|
.Dq no . |
420 |
.It Va headers |
.It Va headers |
421 |
By enabling this variable, message headers (if requested) are displayed, |
By enabling this variable, message headers (if requested) are displayed, |
422 |
besides being written to the log file. The argument must be |
besides being written to the log file. The argument must be |
423 |
.Dq yes |
.Dq yes |
424 |
or |
or |
425 |
.Dq no . |
.Dq no . |
427 |
.Dq no . |
.Dq no . |
428 |
.It Va logfile |
.It Va logfile |
429 |
Full path to log file where filtering information and possible error |
Full path to log file where filtering information and possible error |
430 |
messages are saved to. The command line |
messages are saved to. The command line |
431 |
.Fl l |
.Fl l |
432 |
option overrides this setting. |
option overrides this setting. |
433 |
.It Va namespace |
.It Va namespace |
434 |
When enabled, the program gets the namespace of the user's personal mailboxes, |
When enabled, the program gets the namespace of the user's personal mailboxes, |
435 |
and applies automatically the prefix and hierarchy delimiter to any mailboxes |
and applies automatically the prefix and hierarchy delimiter to any mailboxes |
436 |
residing on the mail server. This must be disabled in cases where the user |
residing on the mail server; the user must use the |
437 |
wants to manually specify mailbox names (eg. because they are not part of the |
.Sq / |
438 |
user's personal namespace mailboxes). The argument must be |
character as the delimiter and |
439 |
|
.Dq |
440 |
|
(ie. nothing) as the prefix, regardless the folder format of the mail server. |
441 |
|
This must be disabled, if the user wants to manually specify mailbox names |
442 |
|
(eg. because they are not part of the user's personal namespace |
443 |
|
mailboxes), in which case he/she should apply the prefix and hierarchy |
444 |
|
delimiter that is used by the mail server. The argument must be |
445 |
.Dq yes |
.Dq yes |
446 |
or |
or |
447 |
.Dq no . |
.Dq no . |
448 |
Default is |
Default is |
449 |
.Dq yes. |
.Dq yes . |
450 |
|
.It Va peek |
451 |
|
When data associated with a message are retrieved, the message is not |
452 |
|
implicitly marked as seen, if this variable is enabled. The argument must be |
453 |
|
.Dq yes |
454 |
|
or |
455 |
|
.Dq no . |
456 |
|
Default is |
457 |
|
.Dq yes . |
458 |
|
.It Va subscribe |
459 |
|
By enabling this variable newly created mailboxes get also subscribed; they |
460 |
|
are set |
461 |
|
.Dq active |
462 |
|
in order for IMAP clients to recognize them. The argument must be |
463 |
|
.Dq yes |
464 |
|
or |
465 |
|
.Dq no . |
466 |
|
Default is |
467 |
|
.Dq no . |
468 |
.It Va timeout |
.It Va timeout |
469 |
The time in seconds, for the program to wait for a mail server's response. |
The time in seconds, for the program to wait for a mail server's response. |
470 |
If not set, then the client will block indefinitely. |
If not set, then the client will block indefinitely. |
472 |
.Sh EXAMPLES |
.Sh EXAMPLES |
473 |
See |
See |
474 |
.Pa sample.imapfilterrc . |
.Pa sample.imapfilterrc . |
475 |
.Sh ENVIROMENT |
.Sh ENVIRONMENT |
476 |
.Bl -tag -width Ds |
.Bl -tag -width Ds |
477 |
.Ev HOME |
.It Ev HOME |
478 |
User's home directory. |
User's home directory. |
479 |
.El |
.El |
480 |
.Sh SEE ALSO |
.Sh SEE ALSO |
481 |
.Xr imapfilter 1 |
.Xr imapfilter 1 |
482 |
.Sh AUTHORS |
.Sh AUTHORS |
483 |
.An Lefteris Chatzibarbas Aq lefcha@users.sourceforge.net |
.An Lefteris Chatzibarbas Aq lefcha@hellug.gr |