imapfilter/imapfilter/imapfilterrc.5

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