imapfilter/imapfilter/imapfilterrc.5

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