1 |
.Dd July 27, 2003 |
2 |
.Dt IMAPFILTERRC 5 |
3 |
.Os |
4 |
.Sh NAME |
5 |
.Nm imapfilterrc |
6 |
.Nd imapfilter configuration file |
7 |
.Sh SYNOPSIS |
8 |
.Pa $HOME/.imapfilterrc |
9 |
.Sh DESCRIPTION |
10 |
The |
11 |
.Nm |
12 |
configuration file consists of a series of commands and variable settings, |
13 |
with each one in a separate line. |
14 |
.Pp |
15 |
Empty lines and lines beginning with the number sign |
16 |
.Sq # |
17 |
character, |
18 |
which |
19 |
are considered comments, are ignored. |
20 |
.Sh COMMANDS |
21 |
.Bl -tag -width Ds |
22 |
.It Cm account Ar alias username[:password]@hostname[:port] [ssl2|ssl3|tls1] |
23 |
Defines a user account under the name |
24 |
.Ar alias , |
25 |
using the |
26 |
.Ar username |
27 |
as user identification and |
28 |
.Ar password |
29 |
as the secret word, connecting to the |
30 |
.Ar hostname |
31 |
mail server, at the specified |
32 |
.Ar port |
33 |
(if not specified the default IMAP protocol port (ie. 143 for imap and 993 |
34 |
for imaps) is used). |
35 |
.Pp |
36 |
SSL/TLS support is enabled with the argument |
37 |
.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 |
50 |
The |
51 |
.Ar username |
52 |
and |
53 |
.Ar password |
54 |
strings can be given in a URL encoding like scheme, that is the |
55 |
.Sq % |
56 |
character followed by two hexadecimal digits representing the encoded |
57 |
character's |
58 |
.Xr ascii 7 |
59 |
code. Within the |
60 |
.Ar username |
61 |
and |
62 |
.Ar password |
63 |
field, any |
64 |
.Sq \&: , |
65 |
.Sq @ , |
66 |
.Sq % |
67 |
or |
68 |
.Sq \ |
69 |
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[,...] |
83 |
Defines folders (mailboxes) and groups them under the |
84 |
.Ar alias |
85 |
name. The mailboxes are associated with the last preceding |
86 |
.Ar account |
87 |
setting. More than one |
88 |
.Ar folder |
89 |
can be declared, separating them with a comma |
90 |
.Sq \&, |
91 |
character. The |
92 |
.Ar alias |
93 |
is comprised by alphanumeric, underscore |
94 |
.Sq _ |
95 |
and minus |
96 |
.Sq - |
97 |
characters. |
98 |
.It Cm filter Ar alias [or|and] |
99 |
Starts the declaration of a filter with the name |
100 |
.Ar alias . |
101 |
Optionally the |
102 |
.Ar and |
103 |
or |
104 |
.Ar or |
105 |
flag can be set, in order to set the mode in which the filter's masks |
106 |
will be combined (default is |
107 |
.Ar and |
108 |
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 |
116 |
A filter entry contains one or more mask entries which are defined with |
117 |
the optional |
118 |
.Ar mask |
119 |
command, the |
120 |
.Ar or |
121 |
or |
122 |
.Ar and |
123 |
flag, the |
124 |
.Ar not |
125 |
flag and the searching criteria, based on which matching of a filter is done. |
126 |
.Pp |
127 |
The |
128 |
.Ar or |
129 |
and |
130 |
.Ar and |
131 |
flags are used to define in which way the current |
132 |
.Ar mask |
133 |
is combined with it's previous |
134 |
.Ar mask . |
135 |
The |
136 |
.Ar not |
137 |
flag is used to revert the functionality of the specified |
138 |
.Ar searchkey . |
139 |
.Pp |
140 |
A |
141 |
.Ar string |
142 |
can be a word, or a phrase enclosed in |
143 |
.Sq \&" . |
144 |
The matching of the |
145 |
.Ar string |
146 |
is case-insensitive. |
147 |
.Pp |
148 |
The available searching criteria are: |
149 |
.Bl -tag -width Ds |
150 |
.It Cm answered |
151 |
Messages that have been answered. |
152 |
.It Cm bcc Ar string |
153 |
Messages that contain the specified |
154 |
.Ar string |
155 |
in the envelope structure's |
156 |
.Dq Bcc |
157 |
field. |
158 |
.It Cm body Ar string |
159 |
Messages that contain the specified |
160 |
.Ar string |
161 |
in the body of the message. |
162 |
.It Cm cc Ar string |
163 |
Messages that contain the specified |
164 |
.Ar string |
165 |
in the envelope structure's |
166 |
.Dq Cc |
167 |
field. |
168 |
.It Cm deleted |
169 |
Messages that are marked for deletion. |
170 |
.It Cm draft |
171 |
Messages that have not completed composition. |
172 |
.It Cm flagged |
173 |
Messages marked for urgent/special attention. |
174 |
.It Cm from Ar string |
175 |
Messages that contain the specified |
176 |
.Ar string |
177 |
in the envelope structure's |
178 |
.Dq From |
179 |
field. |
180 |
.It Cm header Ar fieldname string |
181 |
Messages that have a header with the specified |
182 |
.Ar fieldname , |
183 |
and contain the specified |
184 |
.Ar string |
185 |
in the field body. |
186 |
.It Cm larger Ar number |
187 |
Messages with size larger than the specified |
188 |
.Ar number |
189 |
in octets (bytes). |
190 |
.It Cm new |
191 |
Messages that have |
192 |
.Qq recently |
193 |
arrived in the mailbox (this session is the |
194 |
first, to have been notified about the messages) and have not been read. |
195 |
.It Cm newer Ar number |
196 |
Messages whose internal date is newer than the specified |
197 |
.Ar number |
198 |
of days. |
199 |
.It Cm old |
200 |
Messages that have not |
201 |
.Qq recently |
202 |
arrived in the mailbox and have not been |
203 |
read. |
204 |
.It Cm older Ar number |
205 |
Messages whose internal date is older than the specified |
206 |
.Ar number |
207 |
of days. |
208 |
.It Cm recent |
209 |
Messages that have |
210 |
.Qq recently |
211 |
arrived in the mailbox (this session is the |
212 |
first, to have been notified about the messages). |
213 |
.It Cm seen |
214 |
Messages that have been read. |
215 |
.It Cm smaller Ar number |
216 |
Messages with size smaller than the specified |
217 |
.Ar number |
218 |
in octets (bytes). |
219 |
.It Cm subject Ar string |
220 |
Messages that contain the specified string in the envelope structure's |
221 |
.Dq Subject |
222 |
field. |
223 |
.It Cm unanswered |
224 |
Messages that have not been answered. |
225 |
.It Cm undeleted |
226 |
Messages that are not marked for deletion. |
227 |
.It Cm undraft |
228 |
Messages that have completed composition. |
229 |
.It Cm unflagged |
230 |
Messages that are not marked for urgent/special attention. |
231 |
.It Cm unseen |
232 |
Messages that have not been read. |
233 |
.El |
234 |
.It Cm action Ar type |
235 |
The |
236 |
.Cm action |
237 |
command is used to end the filter entry started with the |
238 |
.Cm filter |
239 |
command. It assigns an action to be done when the filter is matched. |
240 |
.Pp |
241 |
The available |
242 |
.Ar type |
243 |
of actions are: |
244 |
.Bl -tag -width Ds |
245 |
.It Cm copy Ar mailbox [header,...] |
246 |
Copies the messages to the specified |
247 |
.Ar mailbox . |
248 |
If the |
249 |
.Ar mailbox |
250 |
does not exist, then it is created. |
251 |
.Pp |
252 |
Date and time conversion specifiers may be used in the name of the |
253 |
.Ar mailbox . |
254 |
Specifically, a conversion specification consists of a percent sign |
255 |
.Sq % |
256 |
and another character for the current local date and time of the system, |
257 |
and an at sign |
258 |
.Sq @ |
259 |
and another character for the date and time of the message processed. The |
260 |
characters used in the conversion specification are described in |
261 |
.Xr strftime 3 . |
262 |
.Pp |
263 |
The default variable |
264 |
.Dq $_ |
265 |
may be used in the name of the |
266 |
.Ar mailbox , |
267 |
which aliases to the name of the mailbox in which the filter is now applied. |
268 |
.Pp |
269 |
Optionally, fetches and displays the |
270 |
.Ar header |
271 |
of the messages that were copied. |
272 |
.It Cm delete Ar [header,...] |
273 |
Deletes the messages. User can also, optionally, define the |
274 |
.Ar header |
275 |
of the deleted messages to be displayed. More than one |
276 |
.Ar header |
277 |
can be declared and fetched, by separating them with a comma |
278 |
.Sq \&, |
279 |
character. |
280 |
.It Cm flag Ar mode flag[,...] [header,...] |
281 |
Sets the flags of the messages. The |
282 |
.Ar mode |
283 |
can be |
284 |
.Ar replace , |
285 |
.Ar add , |
286 |
or |
287 |
.Ar remove . |
288 |
The |
289 |
.Ar flag |
290 |
can be |
291 |
.Ar none , |
292 |
.Ar seen , |
293 |
.Ar answered , |
294 |
.Ar flagged , |
295 |
.Ar deleted , |
296 |
or |
297 |
.Ar draft . |
298 |
Optionally, the |
299 |
.Ar header |
300 |
of the messages is displayed. |
301 |
.It Cm list Ar [header,...] |
302 |
Just displays the |
303 |
.Ar header |
304 |
of the messages. |
305 |
.It Cm move Ar mailbox [header,...] |
306 |
Moves the messages to the specified |
307 |
.Ar mailbox . |
308 |
If the |
309 |
.Ar mailbox |
310 |
does not exist, then it is created. |
311 |
Date and time conversion specifiers and the default variable |
312 |
may be used in the name of the |
313 |
.Ar mailbox |
314 |
(see the |
315 |
.Ar copy |
316 |
action for more information). Optionally, fetches and displays the |
317 |
.Ar header |
318 |
of the messages that were moved. |
319 |
.It Cm rcopy Ar account mailbox [header,...] |
320 |
Copies the messages to the specified |
321 |
.Ar mailbox |
322 |
residing on a specific |
323 |
.Ar account . |
324 |
Date and time conversion specifiers and the default variable |
325 |
may be used in the name of the |
326 |
.Ar mailbox |
327 |
(see the |
328 |
.Ar copy |
329 |
action for more information). Optionally, displays the |
330 |
.Ar header |
331 |
of the messages. |
332 |
Unlike all other |
333 |
.Ar type |
334 |
of actions, this requires that the message is downloaded from the source |
335 |
mail server and then uploaded to the target mail server. |
336 |
.It Cm rmove Ar account mailbox [header,...] |
337 |
Moves the messages to the specified |
338 |
.Ar mailbox |
339 |
residing on a specific |
340 |
.Ar account . |
341 |
Date and time conversion specifiers and the default variable |
342 |
may be used in the name of the |
343 |
.Ar mailbox |
344 |
(see the |
345 |
.Ar copy |
346 |
action for more information). Optionally, displays the |
347 |
.Ar header |
348 |
of the messages. |
349 |
Unlike all other |
350 |
.Ar type |
351 |
of actions, this requires that the message is downloaded from the source |
352 |
mail server and then uploaded to the target mail server. |
353 |
.El |
354 |
.It Cm job Ar filter[,...] folder[,...] |
355 |
This command is used to define which |
356 |
.Ar filter |
357 |
must be applied to which |
358 |
.Ar folder . |
359 |
More than one |
360 |
.Ar filter |
361 |
and/or |
362 |
.Ar folder |
363 |
can be declared, by separating them with a comma |
364 |
.Sq \&, |
365 |
character. |
366 |
.It Cm [set] Ar variable=value |
367 |
Manipulate and set the configuration variables. |
368 |
.El |
369 |
.Sh VARIABLES |
370 |
.Bl -tag -width Ds |
371 |
.It Va charset |
372 |
Indicates to the server the character set of the strings that appear in the |
373 |
search criteria. It takes a string as an argument. |
374 |
.It Va daemon |
375 |
Enables the daemon mode of |
376 |
.Xr imapfilter 1 . |
377 |
It takes a numeric |
378 |
argument, the polling interval in seconds. |
379 |
.It Va errors |
380 |
By enabling this option any error messages during program's execution get |
381 |
appended to the log file, besides being written to stderr. The argument |
382 |
must be |
383 |
.Dq yes |
384 |
or |
385 |
.Dq no . |
386 |
Default is |
387 |
.Dq no. |
388 |
.It Va expunge |
389 |
Normally messages are marked for deletion and are actually deleted when the |
390 |
mailbox is closed. When this option is enabled, messages are expunged after |
391 |
they are marked deleted. The argument must be |
392 |
.Dq yes |
393 |
or |
394 |
.Dq no . |
395 |
Default is |
396 |
.Dq no . |
397 |
.It Va headers |
398 |
By enabling this variable, message headers (if requested) are displayed, |
399 |
besides being written to the log file. The argument must be |
400 |
.Dq yes |
401 |
or |
402 |
.Dq no . |
403 |
Default is |
404 |
.Dq no . |
405 |
.It Va logfile |
406 |
Full path to log file where filtering information and possible error |
407 |
messages are saved to. The command line |
408 |
.Fl l |
409 |
option overrides this setting. |
410 |
.It Va namespace |
411 |
When enabled, the program gets the namespace of the user's personal mailboxes, |
412 |
and applies automatically the prefix and hierarchy delimiter to any mailboxes |
413 |
residing on the mail server; the user must use the |
414 |
.Sq / |
415 |
character as the delimiter and |
416 |
.Dq |
417 |
(ie. nothing) as the prefix, regardless the folder format of the mail server. |
418 |
This must be disabled, if the user wants to manually specify mailbox names |
419 |
(eg. because they are not part of the user's personal namespace |
420 |
mailboxes), in which case he/she should apply the prefix and hierarchy |
421 |
delimiter that is used by the mail server. The argument must be |
422 |
.Dq yes |
423 |
or |
424 |
.Dq no . |
425 |
Default is |
426 |
.Dq yes . |
427 |
.It Va subscribe |
428 |
By enabling this variable newly created mailboxes get also subscribed; they |
429 |
are set |
430 |
.Dq active |
431 |
in order for IMAP clients to recognize them. The argument must be |
432 |
.Dq yes |
433 |
or |
434 |
.Dq no . |
435 |
Default is |
436 |
.Dq no . |
437 |
.It Va timeout |
438 |
The time in seconds, for the program to wait for a mail server's response. |
439 |
If not set, then the client will block indefinitely. |
440 |
.El |
441 |
.Sh EXAMPLES |
442 |
See |
443 |
.Pa sample.imapfilterrc . |
444 |
.Sh ENVIRONMENT |
445 |
.Bl -tag -width Ds |
446 |
.It Ev HOME |
447 |
User's home directory. |
448 |
.El |
449 |
.Sh SEE ALSO |
450 |
.Xr imapfilter 1 |
451 |
.Sh AUTHORS |
452 |
.An Lefteris Chatzibarbas Aq lefcha@hellug.gr |