imapfilter/imapfilter/imapfilterrc.5

.Dd October 3, 2001
.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,
every one of which must be contained 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 username:password@hostname[:host]
Defines a user account, 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) is used).
.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 @
or
.Sq %
characters must be encoded in the above way.
.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 \&, .
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 filter's masks will be
combined (default is
.Ar and
mode).
.It Cm [mask] Ar [or|and] [not] searchkey
A
.Ar 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 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 old
Messages that have not
.Qq recently
arrived in the mailbox and have not been
read.
.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
.Ar filter
command. It assigns an action to be done when the
.Ar 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 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.
.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.
.El
.Sh VARIABLES
.Bl -tag -width Ds
.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.
.El
.Sh EXAMPLES
See
.Pa sample.imapfilterrc .
.Sh ENVIROMENT
.Bl -tag -width Ds
.Ev HOME
User's home directory.
.El
.Sh SEE ALSO
.Xr imapfilter 1
.Sh AUTHORS
.An Lefteris Chatzibarbas Aq lefcha@users.sourceforge.net
1	lefcha	1.4	.Dd October 3, 2001
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			every one of which must be contained 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.3	.It Cm account Ar username:password@hostname[:host]
23	lefcha	1.1	Defines a user account, using the
24	lefcha	1.2	.Ar username
25	lefcha	1.1	as user identification and
26	lefcha	1.2	.Ar password
27	lefcha	1.1	as the secret word, connecting to the
28	lefcha	1.2	.Ar hostname
29	lefcha	1.1	mail server, at the specified
30	lefcha	1.2	.Ar port
31	lefcha	1.1	(if not specified the default IMAP protocol port (ie. 143) is used).
32	lefcha	1.4	.Pp
33			The
34			.Ar username
35			and
36			.Ar password
37			strings can be given in a URL encoding like scheme, that is the
38			.Sq %
39	lefcha	1.5	character followed by two hexadecimal digits representing the encoded
40			character's
41			.Xr ascii 7
42			code. Within the
43	lefcha	1.4	.Ar username
44			and
45			.Ar password
46			field, any
47			.Sq \&: ,
48			.Sq @
49			or
50			.Sq %
51			characters must be encoded in the above way.
52	lefcha	1.3	.It Cm folder Ar alias folder[,...]
53	lefcha	1.1	Defines folders (mailboxes) and groups them under the
54	lefcha	1.2	.Ar alias
55	lefcha	1.1	name. The mailboxes are associated with the last preceding
56	lefcha	1.2	.Ar account
57	lefcha	1.3	setting. More than one
58			.Ar folder
59			can be declared, separating them with a comma
60			.Sq \&, .
61			The
62			.Ar alias
63			is comprised by alphanumeric, underscore
64			.Sq _
65			and minus
66			.Sq -
67			characters.
68	lefcha	1.2	.It Cm filter Ar alias [or\|and]
69	lefcha	1.1	Starts the declaration of a filter with the name
70	lefcha	1.2	.Ar alias .
71	lefcha	1.1	Optionally the
72	lefcha	1.2	.Ar and
73	lefcha	1.1	or
74	lefcha	1.2	.Ar or
75	lefcha	1.1	flag can be set, in order to set the mode in which filter's masks will be
76			combined (default is
77	lefcha	1.2	.Ar and
78	lefcha	1.1	mode).
79	lefcha	1.2	.It Cm [mask] Ar [or\|and] [not] searchkey
80	lefcha	1.1	A
81	lefcha	1.2	.Ar filter
82	lefcha	1.1	entry contains one or more mask entries which are defined with the optional
83	lefcha	1.2	.Ar mask
84	lefcha	1.1	command, the
85	lefcha	1.2	.Ar or
86	lefcha	1.1	or
87	lefcha	1.2	.Ar and
88			flag, the
89			.Ar not
90	lefcha	1.1	flag and the searching criteria, based on which matching of a filter is done.
91	lefcha	1.2	.Pp
92	lefcha	1.1	The
93	lefcha	1.2	.Ar or
94	lefcha	1.1	and
95	lefcha	1.2	.Ar and
96	lefcha	1.1	flags are used to define in which way the current
97	lefcha	1.2	.Ar mask
98	lefcha	1.1	is combined with it's previous
99	lefcha	1.2	.Ar mask .
100	lefcha	1.1	The
101	lefcha	1.2	.Ar not
102	lefcha	1.1	flag is used to revert the functionality of the specified
103	lefcha	1.2	.Ar searchkey .
104			.Pp
105	lefcha	1.3	A
106			.Ar string
107			can be a word, or a phrase enclosed in
108			.Sq \&" .
109			The matching of the
110			.Ar string
111			is case-insensitive.
112			.Pp
113	lefcha	1.1	The available searching criteria are:
114	lefcha	1.2	.Bl -tag -width Ds
115			.It Cm answered
116	lefcha	1.1	Messages that have been answered.
117	lefcha	1.2	.It Cm bcc Ar string
118	lefcha	1.1	Messages that contain the specified
119	lefcha	1.2	.Ar string
120			in the envelope structure's
121			.Dq Bcc
122	lefcha	1.3	field.
123	lefcha	1.2	.It Cm cc Ar string
124	lefcha	1.1	Messages that contain the specified
125	lefcha	1.2	.Ar string
126			in the envelope structure's
127			.Dq Cc
128	lefcha	1.3	field.
129	lefcha	1.2	.It Cm deleted
130	lefcha	1.1	Messages that are marked for deletion.
131	lefcha	1.2	.It Cm draft
132	lefcha	1.1	Messages that have not completed composition.
133	lefcha	1.2	.It Cm flagged
134	lefcha	1.1	Messages marked for urgent/special attention.
135	lefcha	1.2	.It Cm from 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 From
140	lefcha	1.3	field.
141	lefcha	1.2	.It Cm header Ar fieldname string
142	lefcha	1.1	Messages that have a header with the specified
143	lefcha	1.2	.Ar fieldname ,
144	lefcha	1.1	and contain the specified
145	lefcha	1.2	.Ar string
146	lefcha	1.3	in the field body.
147	lefcha	1.2	.It Cm larger Ar number
148	lefcha	1.1	Messages with size larger than the specified
149	lefcha	1.2	.Ar number
150	lefcha	1.1	in octets (bytes).
151	lefcha	1.2	.It Cm new
152			Messages that have
153	lefcha	1.3	.Qq recently
154	lefcha	1.2	arrived in the mailbox (this session is the
155	lefcha	1.1	first, to have been notified about the messages) and have not been read.
156	lefcha	1.2	.It Cm old
157			Messages that have not
158	lefcha	1.3	.Qq recently
159	lefcha	1.2	arrived in the mailbox and have not been
160	lefcha	1.1	read.
161	lefcha	1.2	.It Cm recent
162			Messages that have
163	lefcha	1.3	.Qq recently
164	lefcha	1.2	arrived in the mailbox (this session is the
165	lefcha	1.1	first, to have been notified about the messages).
166	lefcha	1.2	.It Cm seen
167	lefcha	1.1	Messages that have been read.
168	lefcha	1.2	.It Cm smaller Ar number
169	lefcha	1.1	Messages with size smaller than the specified
170	lefcha	1.2	.Ar number
171	lefcha	1.1	in octets (bytes).
172	lefcha	1.2	.It Cm subject Ar string
173	lefcha	1.1	Messages that contain the specified string in the envelope structure's
174	lefcha	1.2	.Dq Subject
175	lefcha	1.3	field.
176	lefcha	1.2	.It Cm unanswered
177	lefcha	1.1	Messages that have not been answered.
178	lefcha	1.2	.It Cm undeleted
179	lefcha	1.1	Messages that are not marked for deletion.
180	lefcha	1.2	.It Cm undraft
181	lefcha	1.1	Messages that have completed composition.
182	lefcha	1.2	.It Cm unflagged
183	lefcha	1.1	Messages that are not marked for urgent/special attention.
184	lefcha	1.2	.It Cm unseen
185	lefcha	1.1	Messages that have not been read.
186	lefcha	1.2	.El
187			.It Cm action Ar type
188	lefcha	1.1	The
189	lefcha	1.2	.Cm action
190	lefcha	1.1	command is used to end the filter entry started with the
191	lefcha	1.2	.Ar filter
192	lefcha	1.1	command. It assigns an action to be done when the
193	lefcha	1.2	.Ar filter
194	lefcha	1.1	is matched.
195	lefcha	1.2	.Pp
196	lefcha	1.1	The available
197	lefcha	1.2	.Ar type
198	lefcha	1.1	of actions are:
199	lefcha	1.2	.Bl -tag -width Ds
200	lefcha	1.5	.It Cm copy Ar mailbox [header,...]
201			Copies the messages to the specified
202			.Ar mailbox .
203			If the
204			.Ar mailbox
205			does not exist, then it is created. Optionally, fetches and displays the
206			.Ar header
207			of the messages that were copied.
208	lefcha	1.3	.It Cm delete Ar [header,...]
209	lefcha	1.1	Deletes the messages. User can also, optionally, define the
210	lefcha	1.3	.Ar header
211			of the deleted messages to be displayed. More than one
212			.Ar header
213			can be declared and fetched, by separating them with a comma
214			.Sq \&,
215			character.
216	lefcha	1.5	.It Cm list Ar [header,...]
217			Just displays the
218	lefcha	1.3	.Ar header
219	lefcha	1.5	of the messages.
220	lefcha	1.3	.It Cm move Ar mailbox [header,...]
221	lefcha	1.1	Moves the messages to the specified
222	lefcha	1.2	.Ar mailbox .
223	lefcha	1.1	If the
224	lefcha	1.2	.Ar mailbox
225			does not exist, then it is created. Optionally, fetches and displays the
226	lefcha	1.3	.Ar header
227	lefcha	1.2	of the messages that were moved.
228			.El
229	lefcha	1.3	.It Cm job Ar filter[,...] folder[,...]
230	lefcha	1.1	This command is used to define which
231	lefcha	1.3	.Ar filter
232	lefcha	1.1	must be applied to which
233	lefcha	1.3	.Ar folder .
234			More than one
235			.Ar filter
236			and/or
237			.Ar folder
238			can be declared, by separating them with a comma
239			.Sq \&,
240			character.
241			.El
242	lefcha	1.4	.Sh VARIABLES
243	lefcha	1.3	.Bl -tag -width Ds
244	lefcha	1.4	.It Va headers
245	lefcha	1.3	By enabling this variable, message headers (if requested) are displayed,
246	lefcha	1.4	besides being written to the log file. The argument must be
247	lefcha	1.3	.Dq yes
248			or
249			.Dq no .
250			Default is
251			.Dq no .
252	lefcha	1.5	.It Va logfile
253			Full path to log file where filtering information and possible error
254			messages are saved to. The command line
255			.Fl l
256			option overrides this setting.
257	lefcha	1.2	.El
258			.Sh EXAMPLES
259	lefcha	1.1	See
260	lefcha	1.2	.Pa sample.imapfilterrc .
261	lefcha	1.4	.Sh ENVIROMENT
262			.Bl -tag -width Ds
263			.Ev HOME
264			User's home directory.
265			.El
266	lefcha	1.2	.Sh SEE ALSO
267			.Xr imapfilter 1
268	lefcha	1.4	.Sh AUTHORS
269			.An Lefteris Chatzibarbas Aq lefcha@users.sourceforge.net