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