2010-12-29 00:03:09 +00:00
<?xml version='1.0'?>
< !DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"file:///usr/share/xml/docbook/schema/dtd/4.2/docbookx.dtd" [
2011-03-28 21:01:24 +00:00
<!ENTITY lockf '<citerefentry>
<refentrytitle > <emphasis role= "bold" > lockf</emphasis> </refentrytitle>
<manvolnum > 2</manvolnum> </citerefentry> '>
2010-12-29 00:03:09 +00:00
2011-03-28 21:01:24 +00:00
<!ENTITY gzip '<citerefentry>
<refentrytitle > <emphasis role= "bold" > gzip</emphasis> </refentrytitle>
<manvolnum > 1</manvolnum> </citerefentry> '>
2010-12-29 00:03:09 +00:00
2011-03-28 21:01:24 +00:00
<!ENTITY procmail '<citerefentry>
<refentrytitle > <emphasis role= "bold" > procmail</emphasis> </refentrytitle>
<manvolnum > 1</manvolnum> </citerefentry> '>
2010-12-29 00:03:09 +00:00
2011-03-28 21:01:24 +00:00
<!ENTITY python '<citerefentry>
<refentrytitle > <emphasis role= "bold" > python</emphasis> </refentrytitle>
<manvolnum > 1</manvolnum> </citerefentry> '>
2010-12-29 00:03:09 +00:00
2011-03-28 21:01:24 +00:00
<!ENTITY crontab '<citerefentry>
<refentrytitle > <emphasis role= "bold" > crontab</emphasis> </refentrytitle>
<manvolnum > 5</manvolnum> </citerefentry> '>
2010-12-29 00:03:09 +00:00
2011-03-28 21:01:24 +00:00
<!ENTITY mbox '<citerefentry>
<refentrytitle > <emphasis role= "bold" > <acronym > mbox</acronym> </emphasis> </refentrytitle>
<manvolnum > 5</manvolnum> </citerefentry> '>
2010-12-29 00:03:09 +00:00
]>
<refentry >
<docinfo > <date > 9 August 2010</date> </docinfo>
<refmeta >
<refentrytitle > archivemail</refentrytitle>
<manvolnum > 1</manvolnum>
2011-01-07 07:58:40 +00:00
<refmiscinfo class= "manual" > archivemail user manual</refmiscinfo>
<refmiscinfo class= "source" > archivemail 0.8.2</refmiscinfo>
2010-12-29 00:03:09 +00:00
</refmeta>
<refnamediv >
<refname > archivemail</refname>
<refpurpose > archive and compress your old email</refpurpose>
</refnamediv>
<refsynopsisdiv >
<cmdsynopsis >
<command > archivemail</command>
<arg > <option > options</option> </arg>
<arg choice= "req" rep= "repeat" > <replaceable > MAILBOX</replaceable> </arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1 >
<title > Description</title>
<para >
2011-03-28 21:01:24 +00:00
<command > archivemail</command> is a tool for archiving and compressing old
email in mailboxes.
2010-12-29 00:03:09 +00:00
By default it will read the mailbox <replaceable > MAILBOX</replaceable> , moving messages
2011-03-28 21:01:24 +00:00
that are older than the specified number of days (180 by default) to a
2010-12-29 00:03:09 +00:00
&mbox; -format mailbox in the same directory that is compressed
with &gzip; .
It can also just delete old email rather than archive it.
</para>
<para >
By default, <command > archivemail</command> derives the archive filename from the
mailbox name by appending an <filename > _archive</filename> suffix to the mailbox
name. For example, if you run <command > archivemail</command> on a mailbox called
<filename > exsouthrock</filename> , the archive will be created with the
filename <filename > exsouthrock_archive.gz</filename> .
This default behavior can be overridden with command line options, choosing
a custom suffix, a prefix, or a completely custom name for the archive.
</para>
<para >
2011-03-28 21:01:24 +00:00
<command > archivemail</command> supports reading <acronym > IMAP</acronym> ,
<acronym > Maildir</acronym> , <acronym > MH</acronym> and <acronym > mbox</acronym> -format
mailboxes, but always writes <acronym > mbox</acronym> -format archives.
2010-12-29 00:03:09 +00:00
</para>
<para >
Messages that are flagged important are not archived or deleted unless
explicitly requested with the <option > --include-flagged</option> option.
Also, <command > archivemail</command> can be configured not to archive unread mail, or
to only archive messages larger than a specified size.
</para>
<para >
2011-03-28 21:01:24 +00:00
To archive an <acronym > IMAP</acronym> -format mailbox, use the format
2010-12-29 00:03:09 +00:00
<replaceable > imap://username:password@server/mailbox
</replaceable> to specify the mailbox.
2011-03-28 21:01:24 +00:00
<command > archivemail</command> will expand wildcards in <acronym > IMAP</acronym> mailbox
names according to <citation > <acronym > RFC</acronym> 3501</citation> , which says:
<quote > The character "*" is a wildcard, and matches zero or more characters at this
2010-12-29 00:03:09 +00:00
position. The character "%" is similar to "*", but it does not match a
hierarchy delimiter.</quote>
You can omit the password from the <acronym > URL</acronym> ; use the
<option > --pwfile</option> option to make <command > archivemail</command> read the
password from a file, or alternatively just enter it upon request.
If the <option > --pwfile</option> option is set, <command > archivemail</command> does not
look for a password in the <acronym > URL</acronym> , and the colon is not considered a
delimiter.
2011-03-28 21:01:24 +00:00
Substitute <replaceable > imap</replaceable> with
<replaceable > imaps</replaceable> , and <command > archivemail</command> will
establish a secure <acronym > SSL</acronym> connection.
See below for more <acronym > IMAP</acronym> peculiarities.
2010-12-29 00:03:09 +00:00
</para>
</refsect1>
<refsect1 >
<title > Options</title>
<variablelist >
<varlistentry >
2011-03-28 21:01:24 +00:00
<term > <option > -d <replaceable > NUM</replaceable> </option> </term>
<term > <option > --days=<replaceable > NUM</replaceable> </option> </term>
2010-12-29 00:03:09 +00:00
<listitem > <para > Archive messages older than <replaceable > NUM</replaceable> days.
The default is 180. This option is incompatible with the
<option > --date</option> option below.
</para> </listitem>
</varlistentry>
<varlistentry >
2011-03-28 21:01:24 +00:00
<term > <option > -D <replaceable > DATE</replaceable> </option> </term>
<term > <option > --date=<replaceable > DATE</replaceable> </option> </term>
2010-12-29 00:03:09 +00:00
<listitem > <para > Archive messages older than <replaceable > DATE</replaceable> .
2011-03-28 21:01:24 +00:00
<replaceable > DATE</replaceable> can be a date string in ISO format (eg
<quote > 2002-04-23</quote> ), Internet format (<abbrev > eg</abbrev> <quote > 23 Apr
2002</quote> ) or Internet format with full month names (<abbrev > eg</abbrev>
<quote > 23 April 2002</quote> ). Two-digit years are not supported.
2010-12-29 00:03:09 +00:00
This option is incompatible with the <option > --days</option> option above.
</para> </listitem>
</varlistentry>
<varlistentry >
2011-03-28 21:01:24 +00:00
<term > <option > -o <replaceable > PATH</replaceable> </option> </term>
<term > <option > --output-dir=<replaceable > PATH</replaceable> </option> </term>
2010-12-29 00:03:09 +00:00
<listitem > <para > Use the directory name <replaceable > PATH</replaceable> to store the
mailbox archives. The default is the same directory as the mailbox to be
read.
</para> </listitem>
</varlistentry>
<varlistentry >
2011-03-28 21:01:24 +00:00
<term > <option > -P <replaceable > FILE</replaceable> </option> </term>
<term > <option > --pwfile=<replaceable > FILE</replaceable> </option> </term>
<listitem > <para > Read <acronym > IMAP</acronym> password from file
<replaceable > FILE</replaceable> instead of from the command line. Note
that this will probably not work if you are archiving folders from
more than one IMAP account.
2010-12-29 00:03:09 +00:00
</para> </listitem>
</varlistentry>
<varlistentry >
2011-03-28 21:01:24 +00:00
<term > <option > -F <replaceable > STRING</replaceable> </option> </term>
<term > <option > --filter-append=<replaceable > STRING</replaceable> </option> </term>
<listitem > <para > Append <replaceable > STRING</replaceable> to the
<acronym > IMAP</acronym> filter string.
2010-12-29 00:03:09 +00:00
For <acronym > IMAP</acronym> wizards.
</para> </listitem>
</varlistentry>
<varlistentry >
2011-03-28 21:01:24 +00:00
<term > <option > -p <replaceable > NAME</replaceable> </option> </term>
<term > <option > --prefix=<replaceable > NAME</replaceable> </option> </term>
2010-12-29 00:03:09 +00:00
<listitem > <para > Prefix <replaceable > NAME</replaceable> to the archive name.
<replaceable > NAME</replaceable> is expanded by the &python; function
2011-03-28 21:01:24 +00:00
<function > time.strftime()</function> , which means that you can specify special
2010-12-29 00:03:09 +00:00
directives in <replaceable > NAME</replaceable> to make an archive named after the archive
cut-off date.
See the discussion of the <option > --suffix</option> option for a list of valid
2011-03-28 21:01:24 +00:00
<function > strftime()</function> directives.
2010-12-29 00:03:09 +00:00
The default is not to add a prefix.
</para> </listitem>
</varlistentry>
<varlistentry >
2011-03-28 21:01:24 +00:00
<term > <option > -s <replaceable > NAME</replaceable> </option> </term>
<term > <option > --suffix=<replaceable > NAME</replaceable> </option> </term>
2010-12-29 00:03:09 +00:00
<listitem > <para >
Use the suffix <replaceable > NAME</replaceable> to create the filename used for archives.
The default is <filename > _archive</filename> , unless a prefix is specified.
</para>
<para >
Like a prefix, the suffix <replaceable > NAME</replaceable> is expanded by the &python;
2011-03-28 21:01:24 +00:00
function <function > time.strftime()</function> with the archive cut-off date.
<function > time.strftime()</function> understands the following directives:
<variablelist id= "strftime" >
<varlistentry > <term > <code > %a</code> </term>
<listitem > <simpara > Locale's abbreviated weekday name.</simpara> </listitem> </varlistentry>
<varlistentry > <term > <code > %A</code> </term>
<listitem > <simpara > Locale's full weekday name.</simpara> </listitem> </varlistentry>
<varlistentry > <term > <code > %b</code> </term>
<listitem > <simpara > Locale's abbreviated month name.</simpara> </listitem> </varlistentry>
<varlistentry > <term > <code > %B</code> </term>
<listitem > <simpara > Locale's full month name.</simpara> </listitem> </varlistentry>
<varlistentry > <term > <code > %c</code> </term>
<listitem > <simpara > Locale's appropriate date and time representation.</simpara> </listitem> </varlistentry>
<varlistentry > <term > <code > %d</code> </term>
<listitem > <simpara > Day of the month as a decimal number [01,31].</simpara> </listitem> </varlistentry>
<varlistentry > <term > <code > %H</code> </term>
<listitem > <simpara > Hour (24-hour clock) as a decimal number [00,23].</simpara> </listitem> </varlistentry>
<varlistentry > <term > <code > %I</code> </term>
<listitem > <simpara > Hour (12-hour clock) as a decimal number [01,12].</simpara> </listitem> </varlistentry>
<varlistentry > <term > <code > %j</code> </term>
<listitem > <simpara > Day of the year as a decimal number [001,366].</simpara> </listitem> </varlistentry>
<varlistentry > <term > <code > %m</code> </term>
<listitem > <simpara > Month as a decimal number [01,12].</simpara> </listitem> </varlistentry>
<varlistentry > <term > <code > %M</code> </term>
<listitem > <simpara > Minute as a decimal number [00,59].</simpara> </listitem> </varlistentry>
<varlistentry > <term > <code > %p</code> </term>
<listitem > <simpara > Locale's equivalent of either AM or PM.</simpara> </listitem> </varlistentry>
<varlistentry > <term > <code > %S</code> </term>
<listitem > <simpara > Second as a decimal number [00,61]. (1)</simpara> </listitem> </varlistentry>
<varlistentry > <term > <code > %U</code> </term>
<listitem > <simpara > Week number of the year (Sunday as the first day of the week) as a decimal number [00,53]. All days in a new year preceding the first Sunday are considered to be in week 0.</simpara> </listitem> </varlistentry>
<varlistentry > <term > <code > %w</code> </term>
<listitem > <simpara > Weekday as a decimal number [0(Sunday),6].</simpara> </listitem> </varlistentry>
<varlistentry > <term > <code > %W</code> </term>
<listitem > <simpara > Week number of the year (Monday as the first day of the week) as a decimal number [00,53]. All days in a new year preceding the first Sunday are considered to be in week 0.</simpara> </listitem> </varlistentry>
<varlistentry > <term > <code > %x</code> </term>
<listitem > <simpara > Locale's appropriate date representation.</simpara> </listitem> </varlistentry>
<varlistentry > <term > <code > %X</code> </term>
<listitem > <simpara > Locale's appropriate time representation.</simpara> </listitem> </varlistentry>
<varlistentry > <term > <code > %y</code> </term>
<listitem > <simpara > Year without century as a decimal number [00,99].</simpara> </listitem> </varlistentry>
<varlistentry > <term > <code > %Y</code> </term>
<listitem > <simpara > Year with century as a decimal number.</simpara> </listitem> </varlistentry>
<varlistentry > <term > <code > %Z</code> </term>
<listitem > <simpara > Time zone name (or by no characters if no time zone exists).</simpara> </listitem> </varlistentry>
<varlistentry > <term > <code > %%</code> </term>
<listitem > <simpara > A literal <quote > %</quote> character.</simpara> </listitem> </varlistentry>
</variablelist>
2010-12-29 00:03:09 +00:00
</para> </listitem>
</varlistentry>
<varlistentry >
2011-03-28 21:01:24 +00:00
<term > <option > -a <replaceable > NAME</replaceable> </option> </term>
<term > <option > --archive-name=<replaceable > NAME</replaceable> </option> </term>
2010-12-29 00:03:09 +00:00
<listitem > <para > Use <replaceable > NAME</replaceable> as the archive name, ignoring the name
of the mailbox that is archived.
Like prefixes and suffixes, <replaceable > NAME</replaceable> is expanded by
2011-03-28 21:01:24 +00:00
<function > time.strftime()</function> with the archive cut-off date.
2010-12-29 00:03:09 +00:00
Because it hard-codes the archive name, this option cannot be used when
archiving multiple mailboxes.
</para> </listitem>
</varlistentry>
<varlistentry >
2011-03-28 21:01:24 +00:00
<term > <option > -S <replaceable > NUM</replaceable> </option> </term>
<term > <option > --size=<replaceable > NUM</replaceable> </option> </term>
2010-12-29 00:03:09 +00:00
<listitem > <para > Only archive messages that are <replaceable > NUM</replaceable> bytes or
greater.
</para> </listitem>
</varlistentry>
<varlistentry >
2011-03-28 21:01:24 +00:00
<term > <option > -n</option> </term>
<term > <option > --dry-run</option> </term>
2010-12-29 00:03:09 +00:00
<listitem > <para >
Don't write to any files -- just show what would have been done. This is
useful for testing to see how many messages would have been archived.
</para> </listitem>
</varlistentry>
<varlistentry >
2011-03-28 21:01:24 +00:00
<term > <option > -u</option> </term>
<term > <option > --preserve-unread</option> </term>
2010-12-29 00:03:09 +00:00
<listitem > <para >
Do not archive any messages that have not yet been read. <command > archivemail</command>
2011-03-28 21:01:24 +00:00
determines if a message in a <acronym > mbox</acronym> -format or
<acronym > MH</acronym> -format mailbox has been read by looking at the
<literal > Status</literal> header (if it exists). If the status
header is equal to <quote > <literal > RO</literal> </quote> or
<quote > <literal > OR</literal> </quote> then <command > archivemail</command>
assumes the message has been read.
<command > archivemail</command> determines if a <acronym > maildir</acronym>
message has been read by looking at the filename.
If the filename contains an <quote > <literal > S</literal> </quote> after
2010-12-29 00:03:09 +00:00
<filename > :2,</filename> then it assumes the message has been read.
</para> </listitem>
</varlistentry>
<varlistentry >
<term >
<option > --dont-mangle</option>
</term>
<listitem > <para >
2011-03-28 21:01:24 +00:00
Do not mangle lines in message bodies beginning with
<quote > <literal > From </literal> </quote> .
When archiving a message from a mailbox not in <acronym > mbox</acronym>
format, by default <command > archivemail</command> mangles such lines by
prepending a <quote > <literal > > </literal> </quote> to them, since mail user
agents might otherwise interpret these lines as message separators.
Messages from <acronym > mbox</acronym> folders are never mangled. See &mbox; for more
2010-12-29 00:03:09 +00:00
information.
</para> </listitem>
</varlistentry>
<varlistentry >
<term >
<option > --delete</option>
</term>
<listitem > <para >
Delete rather than archive old mail. Use this option with caution!
</para> </listitem>
</varlistentry>
<varlistentry >
<term >
<option > --copy</option>
</term>
<listitem > <para >
Copy rather than archive old mail.
Creates an archive, but the archived messages are not deleted from the
originating mailbox, which is left unchanged.
This is a complement to the <option > --delete</option> option, and mainly useful for
testing purposes.
Note that multiple passes will create duplicates, since messages are blindly
appended to an existing archive.
</para> </listitem>
</varlistentry>
<varlistentry >
<term >
<option > --all</option>
</term>
<listitem > <para >
Archive all messages, without distinction.
</para> </listitem>
</varlistentry>
<varlistentry >
<term >
<option > --include-flagged</option>
</term>
<listitem > <para >
Normally messages that are flagged important are not archived or deleted. If
you specify this option, these messages can be archived or deleted just like
any other message.
</para> </listitem>
</varlistentry>
<varlistentry >
<term >
<option > --no-compress</option>
</term>
<listitem > <para >
Do not compress any archives.
</para> </listitem>
</varlistentry>
<varlistentry >
<term >
<option > --warn-duplicate</option>
</term>
<listitem > <para >
2011-03-28 21:01:24 +00:00
Warn about duplicate <literal > Message-ID</literal> s that appear in the input
2010-12-29 00:03:09 +00:00
mailbox.</para> </listitem>
</varlistentry>
<varlistentry >
2011-03-28 21:01:24 +00:00
<term > <option > -v</option> </term>
<term > <option > --verbose</option> </term>
2010-12-29 00:03:09 +00:00
<listitem > <para >
Reports lots of extra debugging information about what is going on.
</para> </listitem>
</varlistentry>
<varlistentry >
<term >
<option > --debug-imap=<replaceable > NUM</replaceable> </option>
</term>
<listitem > <para >
Set <acronym > IMAP</acronym> debugging level. This makes <command > archivemail</command> dump its
conversation with the <acronym > IMAP</acronym> server and some internal <acronym > IMAP</acronym>
processing to <literal > stdout</literal> . Higher values for <replaceable > NUM</replaceable> give more
elaborate output. Set <replaceable > NUM</replaceable> to 4 to see all exchanged
<acronym > IMAP</acronym> commands. (Actually, <replaceable > NUM</replaceable> is just passed
literally to <literal > imaplib.Debug</literal> .)
</para> </listitem>
</varlistentry>
<varlistentry >
2011-03-28 21:01:24 +00:00
<term > <option > -q</option> </term>
<term > <option > --quiet</option> </term>
2010-12-29 00:03:09 +00:00
<listitem > <para >
Turns on quiet mode. Do not print any statistics about how many messages were
archived. This should be used if you are running <command > archivemail</command> from
cron.
</para> </listitem>
</varlistentry>
<varlistentry >
2011-03-28 21:01:24 +00:00
<term > <option > -V</option> </term>
<term > <option > --version</option> </term>
2010-12-29 00:03:09 +00:00
<listitem > <para >
Display the version of <command > archivemail</command> and exit.
</para> </listitem>
</varlistentry>
<varlistentry >
2011-03-28 21:01:24 +00:00
<term > <option > -h</option> </term>
<term > <option > --help</option> </term>
2010-12-29 00:03:09 +00:00
<listitem > <para >
Display brief summary information about how to run <command > archivemail</command> .
</para> </listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 >
<title > Notes</title>
<para >
<command > archivemail</command> requires &python; version 2.3 or later.
2011-03-28 21:01:24 +00:00
When reading an <acronym > mbox</acronym> -format mailbox, <command > archivemail</command> will
create a lockfile with the extension <filename class= "extension" > .lock</filename> so that
&procmail; will not deliver to the mailbox while it is being processed. It will
2010-12-29 00:03:09 +00:00
also create an advisory lock on the mailbox using &lockf; .
The archive is locked in the same way when it is updated.
<command > archivemail</command> will also complain and abort if a 3rd-party modifies the
mailbox while it is being read.
</para>
<para >
<command > archivemail</command> will always attempt to preserve the
last-access and last-modify times of the input mailbox. Archive
2011-03-28 21:01:24 +00:00
mailboxes are always created with a mode of <literal > 0600</literal> .
2010-12-29 00:03:09 +00:00
If <command > archivemail</command> finds a pre-existing archive mailbox it
will append rather than overwrite that archive.
<command > archivemail</command> will refuse to operate on mailboxes that are symbolic
links.
</para>
<para >
<command > archivemail</command> attempts to find the delivery date of a message by
looking for valid dates in the following headers, in order of precedence:
2011-03-28 21:01:24 +00:00
<literal > Delivery-date</literal> ,
<literal > Received</literal> ,
<literal > Resent-Date</literal> and
<literal > Date</literal> .
2010-12-29 00:03:09 +00:00
If it cannot find any valid date in these headers, it
2011-03-28 21:01:24 +00:00
will use the last-modified file timestamp on <acronym > MH</acronym> and
<acronym > Maildir</acronym> format mailboxes, or the date on the
<literal > From_</literal> line on <acronym > mbox</acronym> -format mailboxes.
2010-12-29 00:03:09 +00:00
</para>
<para >
When archiving mailboxes with leading dots in the name,
2011-03-28 21:01:24 +00:00
<command > archivemail</command> will strip the dots off the archive name, so
2010-12-29 00:03:09 +00:00
that the resulting archive file is not hidden.
This is not done if the <option > --prefix</option> or
<option > --archive-name</option> option is used.
Should there really be mailboxes distinguished only by leading dots in the
name, they will thus be archived to the same archive file by default.
</para>
<para >
A conversion from other formats to &mbox; will silently overwrite existing
2011-03-28 21:01:24 +00:00
<literal > Status</literal> and <literal > X-Status</literal> message headers.
2010-12-29 00:03:09 +00:00
</para>
<refsect2 >
<title > <acronym > IMAP</acronym> </title>
<para >
2011-03-28 21:01:24 +00:00
When <command > archivemail</command> processes an <acronym > IMAP</acronym> folder, all messages
2010-12-29 00:03:09 +00:00
in that folder will have their <literal > \Recent</literal> flag unset, and they will
2011-03-28 21:01:24 +00:00
probably not show up as <quote > new</quote> in your user agent later on.
There is no way around this, it's just how <acronym > IMAP</acronym> works.
2010-12-29 00:03:09 +00:00
This does not apply, however, if you run <command > archivemail</command> with the options
<option > --dry-run</option> or <option > --copy</option> .
</para>
<para >
<command > archivemail</command> relies on server-side searches to determine the messages
that should be archived.
2011-03-28 21:01:24 +00:00
When matching message dates, <acronym > IMAP</acronym> servers refer to server internal
2010-12-29 00:03:09 +00:00
message dates, and these may differ from both delivery time of a message and
2011-03-28 21:01:24 +00:00
its <literal > Date</literal> header.
2010-12-29 00:03:09 +00:00
Also, there exist broken servers which do not implement server side searches.
</para>
2011-03-28 21:01:24 +00:00
<refsect3 > <title > <acronym > IMAP</acronym> <acronym > URL</acronym> s</title>
2010-12-29 00:03:09 +00:00
<para >
2011-03-28 21:01:24 +00:00
<command > archivemail</command> 's <acronym > IMAP</acronym> <acronym > URL</acronym> parser was written
with the <acronym > RFC</acronym> 2882 (<citetitle > Internet Message Format</citetitle> ) rules for
the <token > local-part</token> of email addresses in mind.
2010-12-29 00:03:09 +00:00
So, rather than enforcing an <acronym > URL</acronym> -style encoding of non-<acronym > ascii</acronym>
and reserved characters, it allows to double-quote the username and password.
2011-03-28 21:01:24 +00:00
If your username or password contains the delimiter characters
<quote > @</quote> or <quote > :</quote> , just quote it like this:
<replaceable > imap://"username@bogus.com":"password"@imap.bogus.com/mailbox</replaceable> .
2010-12-29 00:03:09 +00:00
You can use a backslash to escape double-quotes that are part of a quoted
username or password.
Note that quoting only a substring will not work, and be aware that your shell
will probably remove unprotected quotes or backslashes.
</para>
<para >
<command > archivemail</command> tries to be smart when handling mailbox paths.
In particular, it will automatically add an <acronym > IMAP</acronym> <literal > NAMESPACE</literal>
prefix to the mailbox path if necessary; and if you are archiving a subfolder,
you can use the slash as a path separator instead of the <acronym > IMAP</acronym> server's
internal representation.
</para>
</refsect3>
</refsect2>
</refsect1>
<refsect1 >
<title > Examples</title>
<informalexample >
<para >
To archive all messages in the mailbox <filename > debian-user</filename> that
are older than 180 days to a compressed mailbox called
<filename > debian-user_archive.gz</filename> in the current directory:
<screen >
<prompt > bash$ </prompt> <userinput > archivemail debian-user</userinput>
</screen>
</para>
</informalexample>
<informalexample >
<para >
To archive all messages in the mailbox <filename > debian-user</filename> that
are older than 180 days to a compressed mailbox called
<filename > debian-user_October_2001.gz</filename> (where the current month and
year is April, 2002) in the current directory:
<screen >
<prompt > bash$ </prompt> <userinput > archivemail --suffix '_%B_%Y' debian-user</userinput>
</screen>
</para>
</informalexample>
<informalexample >
<para >
To archive all messages in the mailbox <filename > cm-melb</filename> that
are older than the first of January 2002 to a compressed mailbox called
<filename > cm-melb_archive.gz</filename> in the current directory:
<screen >
2011-03-28 21:01:24 +00:00
<prompt > bash$ </prompt> <userinput > archivemail --date='1 Jan 2002' cm-melb</userinput>
2010-12-29 00:03:09 +00:00
</screen>
</para>
</informalexample>
<informalexample >
<para >
2011-03-28 21:01:24 +00:00
Exactly the same as the above example, using an <acronym > ISO</acronym> date format instead:
2010-12-29 00:03:09 +00:00
<screen >
<prompt > bash$ </prompt> <userinput > archivemail --date=2002-01-01 cm-melb</userinput>
</screen>
</para>
</informalexample>
<informalexample >
<para >
To delete all messages in the mailbox <filename > spam</filename> that
are older than 30 days:
<screen >
<prompt > bash$ </prompt> <userinput > archivemail --delete --days=30 spam</userinput>
</screen>
</para>
</informalexample>
<informalexample >
<para >
To archive all read messages in the mailbox <filename > incoming</filename> that
are older than 180 days to a compressed mailbox called
<filename > incoming_archive.gz</filename> in the current directory:
<screen >
<prompt > bash$ </prompt> <userinput > archivemail --preserve-unread incoming</userinput>
</screen>
</para>
</informalexample>
<informalexample >
<para >
To archive all messages in the mailbox <filename > received</filename> that
are older than 180 days to an uncompressed mailbox called
<filename > received_archive</filename> in the current directory:
<screen >
<prompt > bash$ </prompt> <userinput > archivemail --no-compress received</userinput>
</screen>
</para>
</informalexample>
<informalexample >
<para >
To archive all mailboxes in the directory <filename > $HOME/Mail</filename>
that are older than 90 days to compressed mailboxes in the
<filename > $HOME/Mail/Archive</filename> directory:
<screen >
<prompt > bash$ </prompt> <userinput > archivemail -d90 -o $HOME/Mail/Archive $HOME/Mail/*</userinput>
</screen>
</para>
</informalexample>
<informalexample >
<para >
2011-03-28 21:01:24 +00:00
To archive all mails older than 180 days from the given <acronym > IMAP</acronym>
<literal > INBOX</literal> to a compressed mailbox <filename > INBOX_archive.gz</filename> in the
2010-12-29 00:03:09 +00:00
<filename > $HOME/Mail/Archive</filename> directory, quoting the password and
reading it from the environment variable <envar > PASSWORD</envar> :
</para>
<!-- i'm open to suggestions how to avoid making such a super - long line here. -->
<screen >
<prompt > bash$ </prompt> <userinput > archivemail -o $HOME/Mail/Archive imaps://user:'"'$PASSWORD'"'@example.org/INBOX</userinput>
</screen>
<para >
Note the protected quotes.
</para>
</informalexample>
<informalexample >
<para >
2011-03-28 21:01:24 +00:00
To archive all mails older than 180 days in subfolders of <filename
class="directory">foo</filename> on the given <acronym > IMAP</acronym>
server to corresponding archives in the current working directory, reading
the password from the file <filename > ~/imap-pass.txt</filename> :
2010-12-29 00:03:09 +00:00
</para>
<screen >
<prompt > bash$ </prompt> <userinput > archivemail --pwfile=~/imap-pass.txt imaps://user@example.org/foo/*</userinput>
</screen>
</informalexample>
</refsect1>
<refsect1 >
<title > Tips</title>
<para >
Probably the best way to run <command > archivemail</command> is from your &crontab;
file, using the <option > --quiet</option> option.
Don't forget to try the <option > --dry-run</option> and perhaps the
<option > --copy</option> option for non-destructive testing.
</para>
</refsect1>
<refsect1 >
<title > Exit Status</title>
<simpara > Normally the exit status is 0. Nonzero indicates an unexpected error.
</simpara>
</refsect1>
<refsect1 >
<title > Bugs</title>
<simpara >
2011-03-28 21:01:24 +00:00
If an <acronym > IMAP</acronym> mailbox path contains slashes, the archive filename
2010-12-29 00:03:09 +00:00
will be derived from the basename of the mailbox.
If the server's folder separator differs from the Unix slash and is used in the
2011-03-28 21:01:24 +00:00
<acronym > IMAP</acronym> <acronym > URL</acronym> , however, the whole path will be considered
2010-12-29 00:03:09 +00:00
the basename of the mailbox.
2011-03-28 21:01:24 +00:00
<abbrev > E.g.</abbrev> the two <acronym > URL</acronym> s
2010-12-29 00:03:09 +00:00
<userinput > imap://user@example.com/folder/subfolder</userinput> and
<userinput > imap://user@example.com/folder.subfolder</userinput> will be
archived in <filename > subfolder_archive.gz</filename> and
<filename > folder.subfolder_archive.gz</filename> , respectively, although they
2011-03-28 21:01:24 +00:00
might refer to the same <acronym > IMAP</acronym> mailbox.
2010-12-29 00:03:09 +00:00
</simpara>
<simpara >
2011-03-28 21:01:24 +00:00
<command > archivemail</command> does not support reading <acronym > MMDF</acronym> or
<acronym > Babyl</acronym> -format mailboxes. In fact, it will probably think it is
reading an <acronym > mbox</acronym> -format mailbox and cause all sorts of problems.
2010-12-29 00:03:09 +00:00
</simpara>
<simpara >
<command > archivemail</command> is still too slow, but if you are running from &crontab;
2011-03-28 21:01:24 +00:00
you won't care. Archiving <acronym > maildir</acronym> -format mailboxes should be
a lot quicker than <acronym > mbox</acronym> -format mailboxes since it is less
2010-12-29 00:03:09 +00:00
painful for the original mailbox to be reconstructed after selective message
removal.
</simpara>
</refsect1>
<refsect1 >
<title > See Also</title>
2011-03-28 21:01:24 +00:00
<simplelist type= "inline" >
<member > &mbox; </member>
<member > &crontab; </member>
<member > &python; </member>
<member > &procmail; </member>
2010-12-29 00:03:09 +00:00
</simplelist>
</refsect1>
<refsect1 >
2011-03-28 21:01:24 +00:00
<title > <acronym > Url</acronym> </title>
2010-12-29 00:03:09 +00:00
<simpara > The <command > archivemail</command> home page is currently hosted at
<ulink type= "http" url= "http://archivemail.sourceforge.net" > sourceforge</ulink>
</simpara>
</refsect1>
<refsect1 >
<title > Author</title>
<simpara > This manual page was written by Paul Rodger < paul at paulrodger dot
com> . Updated and supplemented by Nikolaus Schulz
<email > microschulz@web.de</email> </simpara>
</refsect1>
</refentry>
