imapfilter/imapfilter/imapfilterrc.5

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