imapfilter/imapfilter/imapfilterrc.5

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