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