imapfilter/imapfilter/imapfilterrc.5

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