"Fossies" - the Fresh Open Source Software Archive 
Member "archivemail-0.9.0/archivemail.xml" (9 Jul 2011, 29201 Bytes) of package /linux/privat/old/archivemail-0.9.0.tar.gz:
As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) XML source code syntax highlighting (style:
standard) with prefixed line numbers.
Alternatively you can here
view or
download the uninterpreted source code file.
1 <?xml version='1.0'?>
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "file:///usr/share/xml/docbook/schema/dtd/4.2/docbookx.dtd" [
4
5 <!ENTITY lockf '<citerefentry>
6 <refentrytitle><emphasis role="bold">lockf</emphasis></refentrytitle>
7 <manvolnum>2</manvolnum></citerefentry>'>
8
9 <!ENTITY gzip '<citerefentry>
10 <refentrytitle><emphasis role="bold">gzip</emphasis></refentrytitle>
11 <manvolnum>1</manvolnum></citerefentry>'>
12
13 <!ENTITY procmail '<citerefentry>
14 <refentrytitle><emphasis role="bold">procmail</emphasis></refentrytitle>
15 <manvolnum>1</manvolnum></citerefentry>'>
16
17 <!ENTITY python '<citerefentry>
18 <refentrytitle><emphasis role="bold">python</emphasis></refentrytitle>
19 <manvolnum>1</manvolnum></citerefentry>'>
20
21 <!ENTITY crontab '<citerefentry>
22 <refentrytitle><emphasis role="bold">crontab</emphasis></refentrytitle>
23 <manvolnum>5</manvolnum></citerefentry>'>
24
25 <!ENTITY mbox '<citerefentry>
26 <refentrytitle><emphasis role="bold"><acronym>mbox</acronym></emphasis></refentrytitle>
27 <manvolnum>5</manvolnum></citerefentry>'>
28 ]>
29
30 <refentry>
31
32 <docinfo><date>5 July 2011</date></docinfo>
33
34 <refmeta>
35 <refentrytitle>archivemail</refentrytitle>
36 <manvolnum>1</manvolnum>
37 <refmiscinfo class="manual">archivemail user manual</refmiscinfo>
38 <refmiscinfo class="source">archivemail 0.9.0</refmiscinfo>
39 </refmeta>
40
41 <refnamediv>
42 <refname>archivemail</refname>
43 <refpurpose>archive and compress your old email</refpurpose>
44 </refnamediv>
45
46 <refsynopsisdiv>
47 <cmdsynopsis>
48
49 <command>archivemail</command>
50 <arg><option>options</option></arg>
51 <arg choice="req" rep="repeat"><replaceable>MAILBOX</replaceable></arg>
52
53 </cmdsynopsis>
54 </refsynopsisdiv>
55
56 <refsect1>
57 <title>Description</title>
58
59 <para>
60 <command>archivemail</command> is a tool for archiving and compressing old
61 email in mailboxes.
62 By default it will read the mailbox <replaceable>MAILBOX</replaceable>, moving
63 messages that are older than the specified number of days (180 by default) to
64 a &mbox;-format mailbox in the same directory that is compressed with &gzip;.
65 It can also just delete old email rather than archive it.
66 </para>
67
68 <para>
69 By default, <command>archivemail</command> derives the archive filename from
70 the mailbox name by appending an <filename>_archive</filename> suffix to the
71 mailbox name. For example, if you run <command>archivemail</command> on a
72 mailbox called <filename>exsouthrock</filename>, the archive will be created
73 with the filename <filename>exsouthrock_archive.gz</filename>.
74 This default behavior can be overridden with command line options, choosing
75 a custom suffix, a prefix, or a completely custom name for the archive.
76 </para>
77
78 <para>
79 <command>archivemail</command> supports reading <acronym>IMAP</acronym>,
80 <acronym>Maildir</acronym>, <acronym>MH</acronym> and
81 <acronym>mbox</acronym>-format mailboxes, but always writes
82 <acronym>mbox</acronym>-format archives.
83 </para>
84
85 <para>
86 Messages that are flagged important are not archived or deleted unless
87 explicitly requested with the <option>--include-flagged</option> option.
88 Also, <command>archivemail</command> can be configured not to archive unread
89 mail, or to only archive messages larger than a specified size.
90 </para>
91
92 <para>
93 To archive an <acronym>IMAP</acronym>-format mailbox, use the format
94 <replaceable>imap://username:password@server/mailbox </replaceable> to specify
95 the mailbox.
96 <command>archivemail</command> will expand wildcards in
97 <acronym>IMAP</acronym> mailbox names according to
98 <citation><acronym>RFC</acronym> 3501</citation>, which says: <quote>The
99 character "*" is a wildcard, and matches zero or more characters at this
100 position. The character "%" is similar to "*", but it does not match a
101 hierarchy delimiter.</quote>
102 You can omit the password from the <acronym>URL</acronym>; use the
103 <option>--pwfile</option> option to make <command>archivemail</command> read
104 the password from a file, or alternatively just enter it upon request.
105 If the <option>--pwfile</option> option is set, <command>archivemail</command>
106 does not look for a password in the <acronym>URL</acronym>, and the colon is
107 not considered a delimiter.
108 Substitute <replaceable>imap</replaceable> with
109 <replaceable>imaps</replaceable>, and <command>archivemail</command> will
110 establish a secure <acronym>SSL</acronym> connection.
111 See below for more <acronym>IMAP</acronym> peculiarities.
112 </para>
113 </refsect1>
114
115 <refsect1>
116 <title>Options</title>
117
118 <variablelist>
119
120 <varlistentry>
121 <term><option>-d <replaceable>NUM</replaceable></option></term>
122 <term><option>--days=<replaceable>NUM</replaceable></option></term>
123 <listitem><para>Archive messages older than <replaceable>NUM</replaceable>
124 days. The default is 180. This option is incompatible with the
125 <option>--date</option> option below.
126 </para></listitem>
127 </varlistentry>
128
129 <varlistentry>
130 <term><option>-D <replaceable>DATE</replaceable></option></term>
131 <term><option>--date=<replaceable>DATE</replaceable></option></term>
132 <listitem><para>Archive messages older than <replaceable>DATE</replaceable>.
133 <replaceable>DATE</replaceable> can be a date string in ISO format (eg
134 <quote>2002-04-23</quote>), Internet format (<abbrev>eg</abbrev> <quote>23 Apr
135 2002</quote>) or Internet format with full month names (<abbrev>eg</abbrev>
136 <quote>23 April 2002</quote>). Two-digit years are not supported.
137 This option is incompatible with the <option>--days</option> option above.
138 </para></listitem>
139 </varlistentry>
140
141 <varlistentry>
142 <term><option>-o <replaceable>PATH</replaceable></option></term>
143 <term><option>--output-dir=<replaceable>PATH</replaceable></option></term>
144 <listitem><para>Use the directory name <replaceable>PATH</replaceable> to
145 store the mailbox archives. The default is the same directory as the mailbox
146 to be read.
147 </para></listitem>
148 </varlistentry>
149
150 <varlistentry>
151 <term><option>-P <replaceable>FILE</replaceable></option></term>
152 <term><option>--pwfile=<replaceable>FILE</replaceable></option></term>
153 <listitem><para>Read <acronym>IMAP</acronym> password from file
154 <replaceable>FILE</replaceable> instead of from the command line. Note
155 that this will probably not work if you are archiving folders from
156 more than one IMAP account.
157 </para></listitem>
158 </varlistentry>
159
160 <varlistentry>
161 <term><option>-F <replaceable>STRING</replaceable></option></term>
162 <term><option>--filter-append=<replaceable>STRING</replaceable></option></term>
163 <listitem><para>Append <replaceable>STRING</replaceable> to the
164 <acronym>IMAP</acronym> filter string.
165 For <acronym>IMAP</acronym> wizards.
166 </para></listitem>
167 </varlistentry>
168
169 <varlistentry>
170 <term><option>-p <replaceable>NAME</replaceable></option></term>
171 <term><option>--prefix=<replaceable>NAME</replaceable></option></term>
172 <listitem><para>Prefix <replaceable>NAME</replaceable> to the archive name.
173 <replaceable>NAME</replaceable> is expanded by the &python; function
174 <function>time.strftime()</function>, which means that you can specify special
175 directives in <replaceable>NAME</replaceable> to make an archive named after
176 the archive cut-off date.
177 See the discussion of the <option>--suffix</option> option for a list of valid
178 <function>strftime()</function> directives.
179 The default is not to add a prefix.
180 </para></listitem>
181 </varlistentry>
182
183 <varlistentry>
184 <term><option>-s <replaceable>NAME</replaceable></option></term>
185 <term><option>--suffix=<replaceable>NAME</replaceable></option></term>
186 <listitem><para>
187 Use the suffix <replaceable>NAME</replaceable> to create the filename used for
188 archives. The default is <filename>_archive</filename>, unless a prefix is
189 specified.
190 </para>
191 <para>
192 Like a prefix, the suffix <replaceable>NAME</replaceable> is expanded by the
193 &python; function <function>time.strftime()</function> with the archive
194 cut-off date. <function>time.strftime()</function> understands the following
195 directives:
196 <variablelist id="strftime">
197 <varlistentry><term><code>%a</code></term>
198 <listitem><simpara>
199 Locale's abbreviated weekday name.
200 </simpara></listitem>
201 </varlistentry>
202 <varlistentry><term><code>%A</code></term>
203 <listitem><simpara>
204 Locale's full weekday name.
205 </simpara></listitem>
206 </varlistentry>
207 <varlistentry><term><code>%b</code></term>
208 <listitem><simpara>
209 Locale's abbreviated month name.
210 </simpara></listitem>
211 </varlistentry>
212 <varlistentry><term><code>%B</code></term>
213 <listitem><simpara>
214 Locale's full month name.
215 </simpara></listitem>
216 </varlistentry>
217 <varlistentry><term><code>%c</code></term>
218 <listitem><simpara>
219 Locale's appropriate date and time representation.
220 </simpara></listitem>
221 </varlistentry>
222 <varlistentry><term><code>%d</code></term>
223 <listitem><simpara>
224 Day of the month as a decimal number [01,31].
225 </simpara></listitem>
226 </varlistentry>
227 <varlistentry><term><code>%H</code></term>
228 <listitem><simpara>
229 Hour (24-hour clock) as a decimal number [00,23].
230 </simpara></listitem>
231 </varlistentry>
232 <varlistentry><term><code>%I</code></term>
233 <listitem><simpara>
234 Hour (12-hour clock) as a decimal number [01,12].
235 </simpara></listitem>
236 </varlistentry>
237 <varlistentry><term><code>%j</code></term>
238 <listitem><simpara>
239 Day of the year as a decimal number [001,366].
240 </simpara></listitem>
241 </varlistentry>
242 <varlistentry><term><code>%m</code></term>
243 <listitem><simpara>
244 Month as a decimal number [01,12].
245 </simpara></listitem>
246 </varlistentry>
247 <varlistentry><term><code>%M</code></term>
248 <listitem><simpara>
249 Minute as a decimal number [00,59].
250 </simpara></listitem>
251 </varlistentry>
252 <varlistentry><term><code>%p</code></term>
253 <listitem><simpara>
254 Locale's equivalent of either AM or PM.
255 </simpara></listitem>
256 </varlistentry>
257 <varlistentry><term><code>%S</code></term>
258 <listitem><simpara>
259 Second as a decimal number [00,61]. (1)
260 </simpara></listitem>
261 </varlistentry>
262 <varlistentry><term><code>%U</code></term>
263 <listitem><simpara>
264 Week number of the year (Sunday as the first day of the week)
265 as a decimal number [00,53]. All days in a new year preceding
266 the first Sunday are considered to be in week 0.
267 </simpara></listitem>
268 </varlistentry>
269 <varlistentry><term><code>%w</code></term>
270 <listitem><simpara>
271 Weekday as a decimal number [0(Sunday),6].
272 </simpara></listitem>
273 </varlistentry>
274 <varlistentry><term><code>%W</code></term>
275 <listitem><simpara>
276 Week number of the year (Monday as the first day of the week)
277 as a decimal number [00,53]. All days in a new year preceding
278 the first Sunday are considered to be in week 0.
279 </simpara></listitem>
280 </varlistentry>
281 <varlistentry><term><code>%x</code></term>
282 <listitem><simpara>
283 Locale's appropriate date representation.
284 </simpara></listitem>
285 </varlistentry>
286 <varlistentry><term><code>%X</code></term>
287 <listitem><simpara>
288 Locale's appropriate time representation.
289 </simpara></listitem>
290 </varlistentry>
291 <varlistentry><term><code>%y</code></term>
292 <listitem><simpara>
293 Year without century as a decimal number [00,99].
294 </simpara></listitem>
295 </varlistentry>
296 <varlistentry><term><code>%Y</code></term>
297 <listitem><simpara>
298 Year with century as a decimal number.
299 </simpara></listitem>
300 </varlistentry>
301 <varlistentry><term><code>%Z</code></term>
302 <listitem><simpara>
303 Time zone name (or by no characters if no time zone exists).
304 </simpara></listitem>
305 </varlistentry>
306 <varlistentry><term><code>%%</code></term>
307 <listitem><simpara>
308 A literal <quote>%</quote> character.
309 </simpara></listitem>
310 </varlistentry>
311 </variablelist>
312 </para></listitem>
313 </varlistentry>
314
315 <varlistentry>
316 <term><option>-a <replaceable>NAME</replaceable></option></term>
317 <term><option>--archive-name=<replaceable>NAME</replaceable></option></term>
318 <listitem><para>Use <replaceable>NAME</replaceable> as the archive name,
319 ignoring the name of the mailbox that is archived.
320 Like prefixes and suffixes, <replaceable>NAME</replaceable> is expanded by
321 <function>time.strftime()</function> with the archive cut-off date.
322 Because it hard-codes the archive name, this option cannot be used when
323 archiving multiple mailboxes.
324 </para></listitem>
325 </varlistentry>
326
327 <varlistentry>
328 <term><option>-S <replaceable>NUM</replaceable></option></term>
329 <term><option>--size=<replaceable>NUM</replaceable></option></term>
330 <listitem><para>Only archive messages that are <replaceable>NUM</replaceable>
331 bytes or greater.
332 </para></listitem>
333 </varlistentry>
334
335 <varlistentry>
336 <term><option>-n</option></term>
337 <term><option>--dry-run</option></term>
338 <listitem><para>
339 Don't write to any files -- just show what would have been done. This is
340 useful for testing to see how many messages would have been archived.
341 </para></listitem>
342 </varlistentry>
343
344 <varlistentry>
345 <term><option>-u</option></term>
346 <term><option>--preserve-unread</option></term>
347 <listitem><para>
348 Do not archive any messages that have not yet been read.
349 <command>archivemail</command> determines if a message in a
350 <acronym>mbox</acronym>-format or <acronym>MH</acronym>-format mailbox has
351 been read by looking at the <literal>Status</literal> header (if it exists).
352 If the status header is equal to <quote><literal>RO</literal></quote> or
353 <quote><literal>OR</literal></quote> then <command>archivemail</command>
354 assumes the message has been read.
355 <command>archivemail</command> determines if a <acronym>maildir</acronym>
356 message has been read by looking at the filename.
357 If the filename contains an <quote><literal>S</literal></quote> after
358 <filename>:2,</filename> then it assumes the message has been read.
359 </para></listitem>
360 </varlistentry>
361
362 <varlistentry>
363 <term>
364 <option>--dont-mangle</option>
365 </term>
366 <listitem><para>
367 Do not mangle lines in message bodies beginning with
368 <quote><literal>From </literal></quote>.
369 When archiving a message from a mailbox not in <acronym>mbox</acronym>
370 format, by default <command>archivemail</command> mangles such lines by
371 prepending a <quote><literal>></literal></quote> to them, since mail user
372 agents might otherwise interpret these lines as message separators.
373 Messages from <acronym>mbox</acronym> folders are never mangled. See &mbox;
374 for more information.
375 </para></listitem>
376 </varlistentry>
377
378 <varlistentry>
379 <term>
380 <option>--delete</option>
381 </term>
382 <listitem><para>
383 Delete rather than archive old mail. Use this option with caution!
384 </para></listitem>
385 </varlistentry>
386
387 <varlistentry>
388 <term>
389 <option>--copy</option>
390 </term>
391 <listitem><para>
392 Copy rather than archive old mail.
393 Creates an archive, but the archived messages are not deleted from the
394 originating mailbox, which is left unchanged.
395 This is a complement to the <option>--delete</option> option, and mainly
396 useful for testing purposes.
397 Note that multiple passes will create duplicates, since messages are blindly
398 appended to an existing archive.
399 </para></listitem>
400 </varlistentry>
401
402 <varlistentry>
403 <term>
404 <option>--all</option>
405 </term>
406 <listitem><para>
407 Archive all messages, without distinction.
408 </para></listitem>
409 </varlistentry>
410
411 <varlistentry>
412 <term>
413 <option>--include-flagged</option>
414 </term>
415 <listitem><para>
416 Normally messages that are flagged important are not archived or deleted. If
417 you specify this option, these messages can be archived or deleted just like
418 any other message.
419 </para></listitem>
420 </varlistentry>
421
422 <varlistentry>
423 <term>
424 <option>--no-compress</option>
425 </term>
426 <listitem><para>
427 Do not compress any archives.
428 </para></listitem>
429 </varlistentry>
430
431 <varlistentry>
432 <term>
433 <option>--warn-duplicate</option>
434 </term>
435 <listitem><para>
436 Warn about duplicate <literal>Message-ID</literal>s that appear in the input
437 mailbox.</para></listitem>
438 </varlistentry>
439
440 <varlistentry>
441 <term><option>-v</option></term>
442 <term><option>--verbose</option></term>
443 <listitem><para>
444 Reports lots of extra debugging information about what is going on.
445 </para></listitem>
446 </varlistentry>
447
448 <varlistentry>
449 <term>
450 <option>--debug-imap=<replaceable>NUM</replaceable></option>
451 </term>
452 <listitem><para>
453 Set <acronym>IMAP</acronym> debugging level. This makes
454 <command>archivemail</command> dump its conversation with the
455 <acronym>IMAP</acronym> server and some internal <acronym>IMAP</acronym>
456 processing to <literal>stdout</literal>. Higher values for
457 <replaceable>NUM</replaceable> give more elaborate output. Set
458 <replaceable>NUM</replaceable> to 4 to see all exchanged
459 <acronym>IMAP</acronym> commands. (Actually, <replaceable>NUM</replaceable>
460 is just passed literally to <literal>imaplib.Debug</literal>.)
461 </para></listitem>
462 </varlistentry>
463
464 <varlistentry>
465 <term><option>-q</option></term>
466 <term><option>--quiet</option></term>
467 <listitem><para>
468 Turns on quiet mode. Do not print any statistics about how many messages were
469 archived. This should be used if you are running
470 <command>archivemail</command> from cron.
471 </para></listitem>
472 </varlistentry>
473
474 <varlistentry>
475 <term><option>-V</option></term>
476 <term><option>--version</option></term>
477 <listitem><para>
478 Display the version of <command>archivemail</command> and exit.
479 </para></listitem>
480 </varlistentry>
481
482 <varlistentry>
483 <term><option>-h</option></term>
484 <term><option>--help</option></term>
485 <listitem><para>
486 Display brief summary information about how to run
487 <command>archivemail</command>.
488 </para></listitem>
489 </varlistentry>
490 </variablelist>
491
492 </refsect1>
493
494 <refsect1>
495 <title>Notes</title>
496
497 <para>
498 <command>archivemail</command> requires &python; version 2.3 or later.
499 When reading an <acronym>mbox</acronym>-format mailbox,
500 <command>archivemail</command> will create a lockfile with the extension
501 <filename class="extension">.lock</filename> so that &procmail; will not
502 deliver to the mailbox while it is being processed. It will also create an
503 advisory lock on the mailbox using &lockf;. The archive is locked in the same
504 way when it is updated.
505 <command>archivemail</command> will also complain and abort if a 3rd-party
506 modifies the mailbox while it is being read.
507 </para>
508
509 <para>
510 <command>archivemail</command> will always attempt to preserve the last-access
511 and last-modify times of the input mailbox. Archive mailboxes are always
512 created with a mode of <literal>0600</literal>.
513 If <command>archivemail</command> finds a pre-existing archive mailbox it will
514 append rather than overwrite that archive.
515 <command>archivemail</command> will refuse to operate on mailboxes that are
516 symbolic links.
517 </para>
518
519 <para>
520 <command>archivemail</command> attempts to find the delivery date of a message
521 by looking for valid dates in the following headers, in order of precedence:
522 <literal>Delivery-date</literal>,
523 <literal>Received</literal>,
524 <literal>Resent-Date</literal> and
525 <literal>Date</literal>.
526 If it cannot find any valid date in these headers, it will use the
527 last-modified file timestamp on <acronym>MH</acronym> and
528 <acronym>Maildir</acronym> format mailboxes, or the date on the
529 <literal>From_</literal> line on <acronym>mbox</acronym>-format mailboxes.
530 </para>
531
532 <para>
533 When archiving mailboxes with leading dots in the name,
534 <command>archivemail</command> will strip the dots off the archive name, so
535 that the resulting archive file is not hidden.
536 This is not done if the <option>--prefix</option> or
537 <option>--archive-name</option> option is used.
538 Should there really be mailboxes distinguished only by leading dots in the
539 name, they will thus be archived to the same archive file by default.
540 </para>
541
542 <para>
543 A conversion from other formats to &mbox; will silently overwrite existing
544 <literal>Status</literal> and <literal>X-Status</literal> message headers.
545 </para>
546
547 <refsect2>
548 <title><acronym>IMAP</acronym></title>
549 <para>
550 When <command>archivemail</command> processes an <acronym>IMAP</acronym>
551 folder, all messages in that folder will have their <literal>\Recent</literal>
552 flag unset, and they will probably not show up as <quote>new</quote> in your
553 user agent later on.
554 There is no way around this, it's just how <acronym>IMAP</acronym> works.
555 This does not apply, however, if you run <command>archivemail</command> with
556 the options <option>--dry-run</option> or <option>--copy</option>.
557 </para>
558 <para>
559 <command>archivemail</command> relies on server-side searches to determine the
560 messages that should be archived.
561 When matching message dates, <acronym>IMAP</acronym> servers refer to server
562 internal message dates, and these may differ from both delivery time of a
563 message and its <literal>Date</literal> header.
564 Also, there exist broken servers which do not implement server side searches.
565 </para>
566 <refsect3><title><acronym>IMAP</acronym> <acronym>URL</acronym>s</title>
567 <para>
568 <command>archivemail</command>'s <acronym>IMAP</acronym>
569 <acronym>URL</acronym> parser was written with the <acronym>RFC</acronym> 2882
570 (<citetitle>Internet Message Format</citetitle>) rules for the
571 <token>local-part</token> of email addresses in mind.
572 So, rather than enforcing an <acronym>URL</acronym>-style encoding of
573 non-<acronym>ascii</acronym> and reserved characters, it allows to
574 double-quote the username and password.
575 If your username or password contains the delimiter characters
576 <quote>@</quote> or <quote>:</quote>, just quote it like this:
577 <replaceable>imap://"username@bogus.com":"password"@imap.bogus.com/mailbox</replaceable>.
578 You can use a backslash to escape double-quotes that are part of a quoted
579 username or password.
580 Note that quoting only a substring will not work, and be aware that your shell
581 will probably remove unprotected quotes or backslashes.
582 </para>
583 <para>
584 Similarly, there is no need to percent-encode non-<acronym>ascii</acronym>
585 characters in <acronym>IMAP</acronym> mailbox names.
586 As long as your locale is configured properly, <command>archivemail</command>
587 should handle these without problems.
588 Note, however, that due to limitations of the <acronym>IMAP</acronym>
589 protocol, non-<acronym>ascii</acronym> characters do not mix well with
590 wildcards in mailbox names.
591 </para>
592 <para>
593 <command>archivemail</command> tries to be smart when handling mailbox paths.
594 In particular, it will automatically add an <acronym>IMAP</acronym>
595 <literal>NAMESPACE</literal> prefix to the mailbox path if necessary; and if
596 you are archiving a subfolder, you can use the slash as a path separator
597 instead of the <acronym>IMAP</acronym> server's internal representation.
598 </para>
599 </refsect3>
600 </refsect2>
601 </refsect1>
602
603 <refsect1>
604 <title>Examples</title>
605
606 <informalexample>
607 <para>
608 To archive all messages in the mailbox <filename>debian-user</filename> that
609 are older than 180 days to a compressed mailbox called
610 <filename>debian-user_archive.gz</filename> in the current directory:
611 <screen>
612 <prompt>bash$ </prompt><userinput>archivemail debian-user</userinput>
613 </screen>
614 </para>
615 </informalexample>
616
617 <informalexample>
618 <para>
619 To archive all messages in the mailbox <filename>debian-user</filename> that
620 are older than 180 days to a compressed mailbox called
621 <filename>debian-user_October_2001.gz</filename> (where the current month and
622 year is April, 2002) in the current directory:
623 <screen>
624 <prompt>bash$ </prompt><userinput>archivemail --suffix '_%B_%Y' debian-user</userinput>
625 </screen>
626 </para>
627 </informalexample>
628
629 <informalexample>
630 <para>
631 To archive all messages in the mailbox <filename>cm-melb</filename> that
632 are older than the first of January 2002 to a compressed mailbox called
633 <filename>cm-melb_archive.gz</filename> in the current directory:
634 <screen>
635 <prompt>bash$ </prompt><userinput>archivemail --date='1 Jan 2002' cm-melb</userinput>
636 </screen>
637 </para>
638 </informalexample>
639
640 <informalexample>
641 <para>
642 Exactly the same as the above example, using an <acronym>ISO</acronym> date
643 format instead:
644 <screen>
645 <prompt>bash$ </prompt><userinput>archivemail --date=2002-01-01 cm-melb</userinput>
646 </screen>
647 </para>
648 </informalexample>
649
650 <informalexample>
651 <para>
652 To delete all messages in the mailbox <filename>spam</filename> that
653 are older than 30 days:
654 <screen>
655 <prompt>bash$ </prompt><userinput>archivemail --delete --days=30 spam</userinput>
656 </screen>
657 </para>
658 </informalexample>
659
660 <informalexample>
661 <para>
662 To archive all read messages in the mailbox <filename>incoming</filename> that
663 are older than 180 days to a compressed mailbox called
664 <filename>incoming_archive.gz</filename> in the current directory:
665 <screen>
666 <prompt>bash$ </prompt><userinput>archivemail --preserve-unread incoming</userinput>
667 </screen>
668 </para>
669 </informalexample>
670
671 <informalexample>
672 <para>
673 To archive all messages in the mailbox <filename>received</filename> that
674 are older than 180 days to an uncompressed mailbox called
675 <filename>received_archive</filename> in the current directory:
676 <screen>
677 <prompt>bash$ </prompt><userinput>archivemail --no-compress received</userinput>
678 </screen>
679 </para>
680 </informalexample>
681
682 <informalexample>
683 <para>
684 To archive all mailboxes in the directory <filename>$HOME/Mail</filename>
685 that are older than 90 days to compressed mailboxes in the
686 <filename>$HOME/Mail/Archive</filename> directory:
687 <screen>
688 <prompt>bash$ </prompt><userinput>archivemail -d90 -o $HOME/Mail/Archive $HOME/Mail/*</userinput>
689 </screen>
690 </para>
691 </informalexample>
692
693 <informalexample>
694 <para>
695 To archive all mails older than 180 days from the given
696 <acronym>IMAP</acronym> <literal>INBOX</literal> to a compressed mailbox
697 <filename>INBOX_archive.gz</filename> in the
698 <filename>$HOME/Mail/Archive</filename> directory, quoting the password and
699 reading it from the environment variable <envar>PASSWORD</envar>:
700 </para>
701 <!-- i'm open to suggestions how to avoid making such a super-long line here. -->
702 <screen>
703 <prompt>bash$ </prompt><userinput>archivemail -o $HOME/Mail/Archive imaps://user:'"'$PASSWORD'"'@example.org/INBOX</userinput>
704 </screen>
705 <para>
706 Note the protected quotes.
707 </para>
708 </informalexample>
709
710 <informalexample>
711 <para>
712 To archive all mails older than 180 days in subfolders of <filename
713 class="directory">foo</filename> on the given <acronym>IMAP</acronym>
714 server to corresponding archives in the current working directory, reading the
715 password from the file <filename>~/imap-pass.txt</filename>:
716 </para>
717 <screen>
718 <prompt>bash$ </prompt><userinput>archivemail --pwfile=~/imap-pass.txt imaps://user@example.org/foo/*</userinput>
719 </screen>
720 </informalexample>
721 </refsect1>
722
723 <refsect1>
724 <title>Tips</title>
725 <para>
726 Probably the best way to run <command>archivemail</command> is from your
727 &crontab; file, using the <option>--quiet</option> option.
728 Don't forget to try the <option>--dry-run</option> and perhaps the
729 <option>--copy</option> option for non-destructive testing.
730 </para>
731 </refsect1>
732
733 <refsect1>
734 <title>Exit Status</title>
735 <simpara>Normally the exit status is 0. Nonzero indicates an unexpected error.
736 </simpara>
737 </refsect1>
738
739 <refsect1>
740 <title>Bugs</title>
741 <simpara>
742 If an <acronym>IMAP</acronym> mailbox path contains slashes, the archive
743 filename will be derived from the basename of the mailbox.
744 If the server's folder separator differs from the Unix slash and is used in
745 the <acronym>IMAP</acronym> <acronym>URL</acronym>, however, the whole path
746 will be considered the basename of the mailbox.
747 <abbrev>E.g.</abbrev> the two <acronym>URL</acronym>s
748 <userinput>imap://user@example.com/folder/subfolder</userinput> and
749 <userinput>imap://user@example.com/folder.subfolder</userinput> will be
750 archived in <filename>subfolder_archive.gz</filename> and
751 <filename>folder.subfolder_archive.gz</filename>, respectively, although they
752 might refer to the same <acronym>IMAP</acronym> mailbox.
753 </simpara>
754 <simpara>
755 <command>archivemail</command> does not support reading
756 <acronym>MMDF</acronym> or <acronym>Babyl</acronym>-format mailboxes. In fact,
757 it will probably think it is reading an <acronym>mbox</acronym>-format mailbox
758 and cause all sorts of problems.
759 </simpara>
760
761 <simpara>
762 <command>archivemail</command> is still too slow, but if you are running from
763 &crontab; you won't care. Archiving <acronym>maildir</acronym>-format
764 mailboxes should be a lot quicker than <acronym>mbox</acronym>-format
765 mailboxes since it is less painful for the original mailbox to be
766 reconstructed after selective message removal.
767 </simpara>
768 </refsect1>
769
770 <refsect1>
771 <title>See Also</title>
772 <simplelist type="inline">
773 <member>&mbox;</member>
774 <member>&crontab;</member>
775 <member>&python;</member>
776 <member>&procmail;</member>
777 </simplelist>
778 </refsect1>
779
780 <refsect1>
781 <title><acronym>Url</acronym></title>
782 <simpara>The <command>archivemail</command> home page is currently hosted at
783 <ulink type="http" url="http://archivemail.sourceforge.net">sourceforge</ulink>
784 </simpara>
785 </refsect1>
786
787 <refsect1>
788 <title>Author</title>
789 <simpara> This manual page was written by Paul Rodger <paul at paulrodger
790 dot com>. Updated and supplemented by Nikolaus Schulz
791 <email>microschulz@web.de</email></simpara>
792 </refsect1>
793
794 </refentry>